ccbudget
v0.1.0
Published
CLI-first Claude usage budget advisor and decision engine (ccbudget).
Maintainers
Readme
ccbudget
CLI-first Claude usage budget advisor and decision engine. It classifies budget failure modes, ranks capability-preserving fallback paths across Opus, Sonnet, and Haiku, and emits structured JSON for tooling.
Requirements
- Node.js 22+ for source builds and npm installs
- macOS only: Xcode command line tools for
codesignwhen building SEA binaries locally
Quick Start
npx ccbudget advisor now --jsonInstall
npm / pnpm
pnpm add -g ccbudget
# or
npm install -g ccbudget
ccbudget advisor now
ccbudget advisor now --jsonGitHub Releases binary
- Open github.com/jamesvillarrubia/ccbudget/releases/latest.
- Download the asset matching your platform, for example
ccbudget-darwin-arm64,ccbudget-linux-x64, orccbudget-win32-x64.exe. - Rename it to
ccbudgetif you want, mark it executable on Unix (chmod +x ccbudget), and move it somewhere on yourPATH. - Run
ccbudget advisor now --json.
The release binaries are built with Node's single executable application workflow.
Claude Code /budget
Install the personal slash-command template:
mkdir -p ~/.claude/commands
curl -fsSL "https://raw.githubusercontent.com/jamesvillarrubia/ccbudget/main/integrations/claude/commands/budget.md" \
-o ~/.claude/commands/budget.mdThen run /budget inside Claude Code. The template shells out to ccbudget advisor now, so make sure ccbudget is already on your PATH.
Build from source
pnpm install
pnpm test
pnpm typecheck
pnpm build
pnpm release:smokeBuild a standalone binary locally
pnpm build
pnpm build:sea
pnpm release:smoke:seaThe local binary is written to release/ccbudget (release\ccbudget.exe on Windows).
Publish checklist
pnpm test
pnpm typecheck
pnpm build
pnpm release:smoke
pnpm build:sea
pnpm release:smoke:sea
pnpm pack:dry-runTagging v* pushes triggers the GitHub release workflow in .github/workflows/release.yml.
Configuration
Spend policy is read from environment variables. The current knobs live in src/config.ts, and the decision-policy rationale lives in docs/superpowers/specs/2026-04-12-ccbudget-decision-engine-design.md.
