cc-budget

cc-budget

A simple Claude Code plugin that lets you set a token or USD budget for your session. It shows your live spend in the status line, warns you when you're close, and blocks expensive tool calls once you go over.

💰 $0.42 / $5.00 · 8%      ← live in your status line

---

Features

• Set a budget — by USD ($5) or tokens (500k tokens)
• Live status line — shows spend vs budget, colored green → yellow (≥80%) → red (over)
• Plan ahead — ask Claude if your goal fits the remaining budget
• Graduated enforcement — nudges at 80%, blocks mutating tools (Edit, Write, Bash) at 100%

---

Installation

1. Clone the repo

git clone https://github.com/AbdurehmanSaleemi/cc-budget.git

2. Open Claude Code and add the marketplace

Inside Claude Code, run:

/plugin marketplace add /full/path/to/cc-budget

Replace /full/path/to/cc-budget with the actual path where you cloned the repo.
For example on Windows: C:\Users\YourName\Documents\cc-budget

3. Install the plugin

/plugin install cc-budget@cc-budget

4. Set up the status line (if not automatic)

If the live spend indicator doesn't appear automatically, add this to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node \"/full/path/to/cc-budget/bin/cc-budget.js\" statusline"
  }
}

---

Commands

Use these commands inside Claude Code:

Command	What it does
/budget set $5	Set a $5 USD budget for this session
/budget set 500k tokens	Set a token budget (also supports 2m tokens, 1m, etc.)
/budget status	Show current spend, remaining, and percentage used
/budget plan <goal>	Check if your goal fits the remaining budget
/budget clear	Remove the budget for this session

Note: A budget is per session. Set it after your first message so there's an active session to attach it to.

---

How it works

Part	How
/budget command	commands/budget.md → runs the engine, prints the result
Status line	settings.json → engine reads live cost from the session
Enforcement	hooks/hooks.json → nudges at 80%, blocks writes at 100%
Session tracking	SessionStart hook keeps a project → session pointer

State is saved under $CLAUDE_PLUGIN_DATA/state/ (falls back to ~/.cc-budget/state/).

---

Pricing reference (per 1M tokens, USD)

Model	Input	Output	Cache write 5m	Cache write 1h	Cache read
Opus 4.8	$5.00	$25.00	$6.25	$10.00	$0.50
Sonnet 4.6	$3.00	$15.00	$3.75	$6.00	$0.30
Haiku 4.5	$1.00	$5.00	$1.25	$2.00	$0.10

Unknown models fall back to Opus rates.

---

Project structure

cc-budget/
├── bin/cc-budget.js     # CLI entry point
├── lib/                 # engine, state, pricing, transcript, budget, format
├── commands/budget.md   # /budget slash command
├── hooks/hooks.json     # SessionStart, UserPromptSubmit, PreToolUse hooks
├── settings.json        # status-line definition
├── .claude-plugin/      # plugin.json + marketplace.json
└── test/                # unit tests (node:test)

---

Development

npm test            # run unit tests
npm run coverage    # run tests with coverage report

---

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the repo
2. Create a branch: git checkout -b my-feature
3. Make your changes and add tests if needed
4. Open a pull request

---

License

MIT — free to use, modify, and distribute. Credit to the author is required.