CodeBudget

Give coding agents the evidence they need, within a budget you control.

CodeBudget is a local Claude Code plugin and CLI. It keeps noisy command output in a retrievable evidence archive, preserves useful diagnostics, and builds task-focused context from your actual source files. CodeBudget stores project configuration and evidence locally. No CodeBudget account or API key is required.

Quickstart · Türkçe başlangıç · Claude plugin · Compatibility · Roadmap

The dashboard reads your local SQLite database and remembers your light/dark preference. Screenshots show disposable browser-test records, not measured provider savings.

What it does

The default mode is observe. Switch to balanced to enable validated reductions. Redaction is separate from optimization. Commands retain executable/argv boundaries and run once; CodeBudget does not rewrite shell commands or grant permissions.

Related MCP server: mcp-intelligence-context

Get started

Free to use, including inside a company. Offering CodeBudget or a modified version as a commercial product, paid bundle or commercial hosted service requires prior written permission from vahapogut. There is no paid CodeBudget tier. These are custom source-available terms; previously published Apache-2.0 material retains its original rights. See the license policy and examples.

Requires Node.js 22.16+ on the 22 line, or Node.js 24, and pnpm 10.33.2. Installation needs network access; core workflows use packaged local assets afterward.

git clone https://github.com/vahapogut/CodeBudget.git
cd CodeBudget
pnpm install --frozen-lockfile
pnpm build

Initialize the project you want to work on, then load the native plugin from that project:

node /absolute/path/to/CodeBudget/dist/cli.js --root /absolute/path/to/your-project init
cd /absolute/path/to/your-project
claude --plugin-dir /absolute/path/to/CodeBudget/plugins/claude-codebudget

Use quoted absolute paths when they contain spaces. Plugin loading is session-scoped: omit --plugin-dir to stop loading it. Avoid registering a second copy of its MCP server. Claude Code 2.1.216 is the exact tested hook-contract version; real model-visible replacement is still an acceptance gate.

To use the CLI from this checkout:

node dist/cli.js init
node dist/cli.js doctor
node dist/cli.js run -- node -e "console.log('hello from CodeBudget')"
node dist/cli.js report --format json
node dist/cli.js dashboard

Open the dashboard URL printed by the CLI. Its access token is local and should stay private. No daemon starts until you request one.

For a portable local installation, use pnpm pack:release and install the resulting archive from dist/. An npm registry release is not yet available; plain pnpm pack is not the release workflow.

Everyday commands

These examples use the installed codebudget binary. You can also use node /absolute/path/to/CodeBudget/dist/cli.js.

# Enable reductions; init starts in observe mode.
codebudget config mode balanced

# Index saved source and build a task-specific package.
codebudget index
codebudget context --task "Fix refresh token rotation" --budget 8000

# Retrieve evidence when a preview is insufficient.
codebudget artifact read <id> --offset 0 --limit 200

# Keep work scoped to a session.
codebudget session start --task "Fix refresh token rotation"
codebudget session checkpoint --session <id>
codebudget report --session <id>
codebudget session close --session <id>

# Preview a project-local client integration.
codebudget adapters install codex --dry-run

# Run free local measurements and preview retention cleanup.
codebudget benchmark replay --corpus all
codebudget benchmark tasks --dry-run
codebudget data prune --dry-run

See codebudget --help and the quickstart for options. Context packages report missing required content and a minimum budget when a complete selection cannot fit. Unsaved editor buffers and hidden client prompts are outside the local index.

What the measurements mean

Smaller output is measurable. Lower total model cost is a hypothesis until tested. CodeBudget keeps these separate:

• Bytes: locally measured content and controlled envelopes.

• Tokens: local estimates or an explicitly selected local encoding; provider message overhead is separate.

• Usage: imported client-reported counters, with missing fields and cumulative counters identified.

• Cost and quota: unknown unless there is appropriate observed evidence. Output reduction does not establish subscription savings.

The benchmark report separates synthetic fixtures from captured tool output. The verification record lists actual commands, platform results and remaining limits. The 30-task harness and its reference solutions are local test infrastructure; they are not completed model experiments.

Privacy and compatibility

Evidence is masked before normal storage and is repository-scoped. Raw archival is a separate explicit opt-in. Redaction is imperfect; the existing coding client still controls what it sends to its provider. run --raw forwards original unmasked machine output while keeping the normal archive masked.

The dashboard has no analytics, remote fonts or hosted backend. It uses loopback authentication and renders evidence as text. Client integrations preserve normal permissions and do not alter global settings. MCP registration exposes tools; it does not intercept every built-in client operation. See privacy, security and the client support matrix.

Develop and verify

pnpm verify          # lint, strict types, local tests, build, browser E2E
pnpm smoke:package   # install the release archive into a clean temporary project
pnpm smoke:clients   # optional: actual installed Codex MCP handshake; no model

The CI matrix runs Node 22 and 24 on Linux, macOS and Windows. Local gates do not invoke a model or publish a package. Results and qualifications are recorded in verification.

Created by vahapogut. Current terms: CodeBudget Free Use License 1.0. Commercial offerings require written permission. Prior Apache-2.0 grants and dependencies' original licenses remain in effect.