https://github.com/roninforge/budgetclaw
Local spend monitor for Claude Code. Zero key, zero prompts, zero latency added.
https://github.com/roninforge/budgetclaw
ai-dev-tools budget-monitor claude-code claude-code-plugin cli-tool cost-monitoring developer-tools open-source spend-tracking token-usage
Last synced: about 2 months ago
JSON representation
Local spend monitor for Claude Code. Zero key, zero prompts, zero latency added.
- Host: GitHub
- URL: https://github.com/roninforge/budgetclaw
- Owner: RoninForge
- License: mit
- Created: 2026-04-09T07:25:27.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T13:10:17.000Z (about 2 months ago)
- Last Synced: 2026-04-27T15:12:07.441Z (about 2 months ago)
- Topics: ai-dev-tools, budget-monitor, claude-code, claude-code-plugin, cli-tool, cost-monitoring, developer-tools, open-source, spend-tracking, token-usage
- Language: Go
- Homepage: https://roninforge.org
- Size: 138 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# budgetclaw
**Local spend monitor for Claude Code.** Watches the JSONL session logs Claude Code writes under `~/.claude/projects`, attributes each tool-call's token cost to a project and git branch, and enforces budget caps by sending SIGTERM to the client process on breach. Pushes phone alerts via ntfy.
**Zero key. Zero prompts. Zero latency added.** budgetclaw never touches API traffic. It parses what Claude Code already writes to disk locally.
```sh
curl -fsSL https://roninforge.org/get | sh
```
## What it does
- Per-project and per-git-branch cost tracking from Claude Code session logs
- Hard budget caps with SIGTERM enforcement on breach
- Phone push alerts via self-hosted or public [ntfy.sh](https://ntfy.sh)
- **Daily audit against Anthropic's models API** -- new models are detected within 24 hours and surfaced via a GitHub issue, so the pricing table cannot silently lag a release
- Works offline, no account, no telemetry leaves your machine
- Single static Go binary, no runtime, no Python, no Node
## Why it exists
After April 2026, solo Claude Code users on raw API billing have no first-party way to cap spend per project or per branch. One stuck agent loop on a feature branch can burn $500 before you notice. Native `/cost` tells you the bill after the fact. budgetclaw tells you *before* and enforces the limit.
## How it works
1. A background watcher tails `~/.claude/projects/*/*.jsonl` using inotify / FSEvents.
2. Each log entry has `usage.*` token counts, `model`, `cwd`, and `timestamp`. budgetclaw reads the cwd, walks up to find `.git/HEAD`, and attributes the event to `{project, branch}`.
3. Token counts are priced against a static table (Opus, Sonnet, Haiku, cache-read, cache-creation) and written to a local SQLite rollup.
4. On each new event, the budget evaluator checks the active limit rules. If a cap is breached, budgetclaw SIGTERMs the matching `claude` process and writes a lockfile to prevent silent relaunch.
5. A phone alert fires via ntfy with the breach context.
No data leaves your machine unless you explicitly opt into a future hosted tier.
## What it does NOT do
- **Does not read your prompts or responses.** It only reads the `usage` and `cwd` fields of each JSONL line.
- **Does not see your API key.** It never talks to Anthropic's API.
- **Does not proxy, intercept, or modify requests.** It is a local log reader.
- **Does not kill arbitrary processes.** It only SIGTERMs processes whose name matches `claude`.
## Install
### One-liner
```sh
curl -fsSL https://roninforge.org/get | sh
```
### Via Homebrew (macOS, Linux)
```sh
brew install roninforge/tap/budgetclaw
```
### From source
```sh
git clone https://github.com/RoninForge/budgetclaw.git
cd budgetclaw
make build
./bin/budgetclaw version
```
### Via `go install`
```sh
go install github.com/RoninForge/budgetclaw/cmd/budgetclaw@latest
```
## Quick start
```sh
# first-run: creates config + state dirs, prints paths
budgetclaw init
# cap the "myapp" project at $5/day across all branches, kill on breach
budgetclaw limit set --project myapp --period daily --cap 5.00 --action kill
# cap the "feature/expensive" branch specifically at $1/day, warn only
budgetclaw limit set --project myapp --branch "feature/expensive" --period daily --cap 1.00 --action warn
# show today's spend by project and branch
budgetclaw status
# run the watcher in the foreground
budgetclaw watch
```
## Configuration
budgetclaw follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html):
| Kind | Path |
| ------ | ---------------------------------------- |
| Config | `$XDG_CONFIG_HOME/budgetclaw/config.toml` |
| State | `$XDG_STATE_HOME/budgetclaw/state.db` |
| Data | `$XDG_DATA_HOME/budgetclaw/` |
| Cache | `$XDG_CACHE_HOME/budgetclaw/` |
When the XDG variables are unset, defaults are `~/.config`, `~/.local/state`, `~/.local/share`, and `~/.cache`.
See [`examples/config.toml`](examples/config.toml) for a documented template.
## Phone alerts via ntfy
budgetclaw pushes breach notifications to your phone via [ntfy.sh](https://ntfy.sh) (or any self-hosted ntfy instance). When a budget cap is breached, you get an instant push notification with the project, branch, and spend amount.
Setup takes 60 seconds:
```sh
# 1. Install the ntfy app on your phone (iOS or Android)
# https://ntfy.sh/docs/subscribe/phone/
# 2. Generate a secret topic name
TOPIC="budgetclaw-$(openssl rand -hex 12)"
echo "Your topic: $TOPIC"
# 3. Subscribe to that topic in the ntfy app
# 4. Configure budgetclaw
budgetclaw alerts setup --server https://ntfy.sh --topic "$TOPIC"
# 5. Test delivery
budgetclaw alerts test
```
You should see a "budgetclaw test" notification on your phone. From now on, warn and kill breaches will push automatically. Kill actions use max priority to bypass Do Not Disturb.
## Pricing freshness
Anthropic ships new models often, and a missing model in the pricing table means events get silently skipped from the rollups (no cost recorded, no cap fired). budgetclaw guards against that with a daily GitHub Action ([`.github/workflows/pricing-audit.yml`](.github/workflows/pricing-audit.yml)) that:
1. Calls Anthropic's `/v1/models` metadata endpoint (free, no inference billed).
2. Diffs the model list against the embedded pricing table.
3. Opens a GitHub issue if a new model is detected.
A maintainer then verifies pricing on the [Anthropic pricing page](https://docs.anthropic.com/en/docs/about-claude/pricing) and ships a patch release. **Detection is automated; pricing is verified by hand** -- a wrong auto-merged price would compromise the kill action, so the verification step stays human.
If you ever notice `budgetclaw status` reporting suspiciously low spend, run `budgetclaw pricing diagnose` to see which models the local logs contain and whether any are missing from the table. The same fix flow applies: open an issue, we add the entry, you upgrade and run `budgetclaw backfill` to recover historical attribution.
The model audit catches new model IDs but not changes to existing rates -- Anthropic's `/v1/models` returns metadata only, no pricing. As a second line of defense, the maintainer cross-checks rates against the [Anthropic pricing page](https://docs.anthropic.com/en/docs/about-claude/pricing) and the community-maintained [`model_prices_and_context_window.json`](https://github.com/BerriAI/litellm/blob/main/litellm/model_prices_and_context_window_backup.json) periodically. v0.1.4 corrected the Opus 4.5 / 4.6 / 4.7 rates from the pre-cut $15 / $75 to the current $5 / $25 after a cross-check turned up the gap. If a price correction lands, run `budgetclaw backfill --rebuild` to recompute historical rollups; without `--rebuild`, idempotent inserts leave the old rate baked into existing rows.
## Security
budgetclaw only reads from `$HOME/.claude/projects/` and only SIGTERMs processes named `claude`. It writes only to its own XDG directories. See [SECURITY.md](SECURITY.md) for the responsible-disclosure policy.
## Roadmap
- v0.1: local JSONL parser, per-project/branch rollups, budget caps, SIGTERM enforcer, ntfy alerts, Claude Code plugin manifest
- v0.2: per-branch forecasting, multiple budget periods, shell completion
- v0.3: launchd/systemd daemon integration, Homebrew tap
- Later: optional hosted sync tier, Cursor per-branch attribution (on top of Cursor's native caps)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs welcome.
## License
MIT. See [LICENSE](LICENSE).
## About
budgetclaw is part of [RoninForge](https://roninforge.org), a small venture building honest tools for the army of one. Source: [github.com/RoninForge/budgetclaw](https://github.com/RoninForge/budgetclaw).