{
  "markdown": "# budgetclaw\n\nRoninForge BudgetClaw is a local spend monitor for Claude Code that tracks token cost per\nproject and per git branch and stops a runaway agent before a budget cap is breached. It is\nMIT licensed, runs entirely on your machine, and requires no API keys.\n\nPart of [RoninForge.org](https://roninforge.org), an independent open-source workshop that\nkeeps dated, reproducible records of the AI developer tooling economy.\n\nBudgetClaw watches the JSONL session logs Claude Code already writes under `~/.claude/projects`, attributes each response's token cost to a `{project, branch}` pair, and when a cap is breached it sends SIGTERM to the Claude Code process and pushes a phone alert via ntfy.\n\n**Zero API keys. Zero prompts. Zero latency added.** budgetclaw never touches API traffic. It reads local log files that already exist on your disk.\n\nDocs, the ccusage comparison, the team guide and the pricing methodology: **<https://roninforge.org/budgetclaw/>**\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\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\nWorks with ntfy.sh or any self-hosted ntfy instance. Kill actions use max priority so they bypass Do Not Disturb.\n\n## Pricing\n\nRates come from the open [ai-price-index](https://roninforge.org/data/ai-price-index/) dataset (CC BY 4.0), embedded in the binary at build time, so pricing works offline by default. Each event is priced at the rate that was effective on its own date, not today's rate.\n\nAn event whose model the table does not recognise is **stored with its full token counts** rather than discarded, and prices itself once the table learns the model. `budgetclaw status` marks any total covering unpriced events with a trailing `+` and names the models involved.\n\n```sh\n# which models your logs contain, and whether each has a rate\nbudgetclaw pricing diagnose\n\n# opt in to fetching the signed price table over the network (off by default)\nbudgetclaw pricing auto on\nbudgetclaw pricing refresh\n```\n\nA fetched table is only used if its Ed25519 signature verifies against a key compiled into your binary and the contents pass plausibility checks; otherwise it is discarded and the table already in force is kept.\n\n> **Do not run `backfill --rebuild` after a price change.** It wipes the database and replays from Claude Code's session logs, which are pruned after roughly a month while the database keeps everything, so it can discard months of spend. It refuses when it would, and needs `--force` to override. Its remaining purpose is repairing a database written by a pre-dedupe binary. Nothing needs running after a price change: [why that is](https://roninforge.org/budgetclaw/#pricing-freshness).\n\n## Sync to Goei\n\nOne command pushes your locally computed rollup to [Goei](https://roninforge.org/goei/), the hosted dashboard that dedupes spend across machines and teammates.\n\n```sh\n# 1. In Goei, go to Settings -> Device Tokens and create a token (starts with goei_dt_)\n\n# 2. Sync the last 30 days\nbudgetclaw sync --token goei_dt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# Or keep the token out of your shell history:\nexport GOEI_DEVICE_TOKEN=goei_dt_...\nbudgetclaw sync --days 7\n\n# Preview what would be sent without sending it:\nbudgetclaw sync --dry-run\n```\n\nOr store the token in config so a bare `budgetclaw sync` works:\n\n```toml\n[goei]\ntoken = \"goei_dt_...\"\n# endpoint = \"https://goei.roninforge.org/api/ingest\"  # optional override for self-hosting\n# machine = \"my-laptop\"  # optional; defaults to the OS hostname\n```\n\nOnly aggregate dollar and token totals per project, branch, model and day are transmitted. No Anthropic key is involved and none leaves your machine. Re-running sync is safe: Goei deduplicates by `(day, model, project, branch)`, so re-sending a day overwrites rather than double-counts.\n\nFlags: `--days N` (default 30), `--since YYYY-MM-DD`, `--machine LABEL`, `--no-branch` to collapse every branch into one project row, `--dry-run`.\n\nUpgrading from a version before per-machine identity shows a one-time double-count over the re-synced window: [what to expect and why](https://roninforge.org/budgetclaw/#team).\n\n## Scope and security\n\n- Reads only the `usage`, `model`, `cwd` and `timestamp` fields of `~/.claude/projects/*.jsonl`. It does not read prompts or responses.\n- Never sees your API key. It never talks to Anthropic's API and never sits between your editor and it.\n- Only sends SIGTERM to processes named `claude`. It writes only to its own XDG directories.\n- Makes no network request until you turn one on. `budgetclaw sync` and `budgetclaw pricing auto on` are both opt-in and off by default.\n\nSee [SECURITY.md](SECURITY.md) for the responsible-disclosure policy.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs welcome.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Docs\n\n- [How to set a hard spend cap on Claude Code](https://roninforge.org/tutorials/how-to-set-a-hard-spend-cap-on-claude-code/)\n- [How to track your Claude Code spend over time](https://roninforge.org/tutorials/how-to-track-claude-code-spend-over-time/)\n- [How to minimize Claude Code costs](https://roninforge.org/tutorials/how-to-minimize-claude-code-costs/)\n- [Track Claude Code spend across a team](https://roninforge.org/goei/track-claude-code-spend-across-team/)\n- [Goei vs ccusage](https://roninforge.org/goei/vs-ccusage/)\n- [Why a price change should not restate your recorded history](https://roninforge.org/data/ai-price-index/back-dating/)\n\nbudgetclaw is part of [RoninForge.org](https://roninforge.org).\n",
  "bytes": 7472,
  "sha": "dd20931c543cca1545976111dea97093a704d3cc6d3b6b73e698889dcebb3204",
  "repo_slug": "roninforge/budgetclaw",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_roninforge_budgetclaw_budgetclaw_b4fc5b09/readme"
}