{"id":48639020,"url":"https://github.com/roninforge/budgetclaw","last_synced_at":"2026-04-28T07:01:08.823Z","repository":{"id":350186220,"uuid":"1205681381","full_name":"RoninForge/budgetclaw","owner":"RoninForge","description":"Local spend monitor for Claude Code. Zero key, zero prompts, zero latency added.","archived":false,"fork":false,"pushed_at":"2026-04-27T13:10:17.000Z","size":141,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T15:12:07.441Z","etag":null,"topics":["ai-dev-tools","budget-monitor","claude-code","claude-code-plugin","cli-tool","cost-monitoring","developer-tools","open-source","spend-tracking","token-usage"],"latest_commit_sha":null,"homepage":"https://roninforge.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RoninForge.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T07:25:27.000Z","updated_at":"2026-04-27T13:10:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/RoninForge/budgetclaw","commit_stats":null,"previous_names":["roninforge/budgetclaw"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/RoninForge/budgetclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoninForge%2Fbudgetclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoninForge%2Fbudgetclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoninForge%2Fbudgetclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoninForge%2Fbudgetclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RoninForge","download_url":"https://codeload.github.com/RoninForge/budgetclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoninForge%2Fbudgetclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32370030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-dev-tools","budget-monitor","claude-code","claude-code-plugin","cli-tool","cost-monitoring","developer-tools","open-source","spend-tracking","token-usage"],"created_at":"2026-04-09T15:01:37.620Z","updated_at":"2026-04-28T07:01:08.816Z","avatar_url":"https://github.com/RoninForge.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# budgetclaw\n\n**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.\n\n**Zero key. Zero prompts. Zero latency added.** budgetclaw never touches API traffic. It parses what Claude Code already writes to disk locally.\n\n```sh\ncurl -fsSL https://roninforge.org/get | sh\n```\n\n## What it does\n\n- Per-project and per-git-branch cost tracking from Claude Code session logs\n- Hard budget caps with SIGTERM enforcement on breach\n- Phone push alerts via self-hosted or public [ntfy.sh](https://ntfy.sh)\n- **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\n- Works offline, no account, no telemetry leaves your machine\n- Single static Go binary, no runtime, no Python, no Node\n\n## Why it exists\n\nAfter 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.\n\n## How it works\n\n1. A background watcher tails `~/.claude/projects/*/*.jsonl` using inotify / FSEvents.\n2. 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}`.\n3. Token counts are priced against a static table (Opus, Sonnet, Haiku, cache-read, cache-creation) and written to a local SQLite rollup.\n4. 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.\n5. A phone alert fires via ntfy with the breach context.\n\nNo data leaves your machine unless you explicitly opt into a future hosted tier.\n\n## What it does NOT do\n\n- **Does not read your prompts or responses.** It only reads the `usage` and `cwd` fields of each JSONL line.\n- **Does not see your API key.** It never talks to Anthropic's API.\n- **Does not proxy, intercept, or modify requests.** It is a local log reader.\n- **Does not kill arbitrary processes.** It only SIGTERMs processes whose name matches `claude`.\n\n## Install\n\n### One-liner\n\n```sh\ncurl -fsSL https://roninforge.org/get | sh\n```\n\n### Via Homebrew (macOS, Linux)\n\n```sh\nbrew install roninforge/tap/budgetclaw\n```\n\n### From source\n\n```sh\ngit clone https://github.com/RoninForge/budgetclaw.git\ncd budgetclaw\nmake build\n./bin/budgetclaw version\n```\n\n### Via `go install`\n\n```sh\ngo install github.com/RoninForge/budgetclaw/cmd/budgetclaw@latest\n```\n\n## Quick start\n\n```sh\n# first-run: creates config + state dirs, prints paths\nbudgetclaw init\n\n# cap the \"myapp\" project at $5/day across all branches, kill on breach\nbudgetclaw limit set --project myapp --period daily --cap 5.00 --action kill\n\n# cap the \"feature/expensive\" branch specifically at $1/day, warn only\nbudgetclaw limit set --project myapp --branch \"feature/expensive\" --period daily --cap 1.00 --action warn\n\n# show today's spend by project and branch\nbudgetclaw status\n\n# run the watcher in the foreground\nbudgetclaw watch\n```\n\n## Configuration\n\nbudgetclaw follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html):\n\n| Kind   | Path                                     |\n| ------ | ---------------------------------------- |\n| Config | `$XDG_CONFIG_HOME/budgetclaw/config.toml` |\n| State  | `$XDG_STATE_HOME/budgetclaw/state.db`     |\n| Data   | `$XDG_DATA_HOME/budgetclaw/`              |\n| Cache  | `$XDG_CACHE_HOME/budgetclaw/`             |\n\nWhen the XDG variables are unset, defaults are `~/.config`, `~/.local/state`, `~/.local/share`, and `~/.cache`.\n\nSee [`examples/config.toml`](examples/config.toml) for a documented template.\n\n## Phone alerts via ntfy\n\nbudgetclaw 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.\n\nSetup takes 60 seconds:\n\n```sh\n# 1. Install the ntfy app on your phone (iOS or Android)\n#    https://ntfy.sh/docs/subscribe/phone/\n\n# 2. Generate a secret topic name\nTOPIC=\"budgetclaw-$(openssl rand -hex 12)\"\necho \"Your topic: $TOPIC\"\n\n# 3. Subscribe to that topic in the ntfy app\n\n# 4. Configure budgetclaw\nbudgetclaw alerts setup --server https://ntfy.sh --topic \"$TOPIC\"\n\n# 5. Test delivery\nbudgetclaw alerts test\n```\n\nYou 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.\n\n## Pricing freshness\n\nAnthropic 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:\n\n1. Calls Anthropic's `/v1/models` metadata endpoint (free, no inference billed).\n2. Diffs the model list against the embedded pricing table.\n3. Opens a GitHub issue if a new model is detected.\n\nA 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.\n\nIf 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.\n\nThe 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.\n\n## Security\n\nbudgetclaw 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.\n\n## Roadmap\n\n- v0.1: local JSONL parser, per-project/branch rollups, budget caps, SIGTERM enforcer, ntfy alerts, Claude Code plugin manifest\n- v0.2: per-branch forecasting, multiple budget periods, shell completion\n- v0.3: launchd/systemd daemon integration, Homebrew tap\n- Later: optional hosted sync tier, Cursor per-branch attribution (on top of Cursor's native caps)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs welcome.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## About\n\nbudgetclaw 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froninforge%2Fbudgetclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froninforge%2Fbudgetclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froninforge%2Fbudgetclaw/lists"}