budgetary.tools

Know what a coding task will cost — or know that we don't know. Never a confident guess.

Budgetary gives your AI coding agent a pre-flight token-spend estimate: a range, a scenario, and a confidence signal — before the task runs. Where it has no coverage, it says so. Free and unlimited.

Install (Claude Code)

claude mcp add budgetary \
  --env BUDGETARY_API_KEY=bg_test_YOUR_KEY \
  --env BUDGETARY_HOST=claude-code \
  -- npx -y @budgetary/mcp

Other agents and editors below. Use a free bg_test_ key to start.

Install options

The honest version

What it does, and what it doesn't

What Budgetary does

Measures real spend after a run, so estimates are grounded in what actually happened.
Forecasts where it has coverage — a token range with a confidence signal, not a single magic number.
Aggregates across branch and project, so you can see spend in context.
Says "no read" honestly when a task is too unlike anything it has seen.
Free and unlimited — a shareware posture, no metering games.

What Budgetary does not do

Not a guaranteed predictor. Forecasts are coverage-local and always qualified.
Never fabricates a token count. If it can't estimate, it returns a "no read" — not a number.
Not per-keystroke. It estimates a task before you run it; it isn't a live meter.
Doesn't index your repo. It reads the task you describe, not your codebase.
No ex-ante foresight today beyond where it has coverage — and it tells you the edges.

Install

One MCP server, any agent

Budgetary is an MCP server. Add it to your agent and it exposes one tool — estimate. Start with a free bg_test_ key.

Claude Code — plugin

/plugin marketplace add thriftell/budgetary-clients
/plugin install budgetary@budgetary
/reload-plugins

Claude Code prompts for your API key during install and stores it in your system keychain. The plugin is also what wires the session-end hook that submits your real token counts — a bare claude mcp add gives you the estimate tool on its own.

Any MCP agent — stdio

npx -y @budgetary/mcp
# requires env BUDGETARY_API_KEY=bg_test_…  (free tier) or bg_live_…

Or point your agent at the hosted server directly: https://api.budgetary.tools/mcp (streamable-http, bearer auth). It estimates only. There is no local process on that path — no pending store, no session-end hook, no transcript to read — so a run estimated through it is never closed out by an actual, by any route. Hand-configure it or not at all: the registry listing no longer advertises it, because a listing entry carries a URL and nothing else.

VS Code

1. Install "Budgetary" (budgetary.budgetary-vscode) from Open VSX.
2. Run the command:  Budgetary: Sign In
3. Paste your API key (bg_test_… free, or bg_live_…) when prompted.

Open VSX listing: budgetary.budgetary-vscode.

Copy-paste prompts

Wire it up, then watch it work

Two prompts per platform. Onboarding tells your agent exactly how to add Budgetary — it states what it does and never writes a key without your say-so. Demo shows the estimate tool in use. Once installed, the pre-flight estimate happens on its own.

Claude Code

◐ actuals: auto with the plugin

a · Onboarding — paste into the agent

Set up Budgetary so you give me a pre-flight token-spend estimate before large tasks.

Do exactly this, and nothing more:
1. Ask me for my Budgetary API key first (it starts with bg_test_ or bg_live_). If I don't give you one, stop and tell me — do not invent or read one from anywhere.
2. Add a single MCP server named "budgetary" from the published npm package:
   claude mcp add budgetary --env BUDGETARY_API_KEY=<the key I gave you> --env BUDGETARY_HOST=claude-code -- npx -y @budgetary/mcp
3. Then tell me, in one line: that command wires the "estimate" tool only. Automatic actuals — the session-end hook that submits what a run really cost — come with the Claude Code plugin (/plugin marketplace add thriftell/budgetary-clients, then /plugin install budgetary@budgetary). Do not install it unless I ask.

This only registers one MCP server (it exposes an "estimate" tool). It does not edit my code, read my repository, or install anything else. Do not write the key to any other file or commit it.

b · Demo — see the estimate tool in use

Before you start, call the Budgetary "estimate" tool on this task and show me what it returns — the token range, the scenario, and the confidence — then wait for my go-ahead:

  "Refactor the auth middleware to use async sessions and update the tests."

If Budgetary returns a "no read" (it can't confidently estimate this one), just tell me that plainly. Don't guess a number.

Actuals: automatic with the Claude Code plugin — that is what wires the session-end hook that submits your real token counts. The command above adds the estimate tool alone: estimates work, and until that hook is in place you submit actuals yourself from the real session transcript (npx @budgetary/mcp on-session-end --transcript <file>), so you never type a number. Run npx @budgetary/mcp doctor to see whether an automatic submission has ever run on this machine — it prints the hook to add if none has.

Cursor

○ actuals: estimate-only

a · Onboarding — paste into the agent

Create a file at .cursor/mcp.json in this project with exactly the JSON below, then tell me to reload MCP servers in Cursor's settings.

Ask me for my Budgetary API key first (bg_test_ or bg_live_ prefix) and drop it into the BUDGETARY_API_KEY field. Do not store it anywhere else, and do not commit this file. This adds one MCP server (the "estimate" tool) and changes nothing else.

{
  "mcpServers": {
    "budgetary": {
      "command": "npx",
      "args": ["-y", "@budgetary/mcp"],
      "env": { "BUDGETARY_API_KEY": "bg_test_YOUR_KEY" }
    }
  }
}

b · Demo — see the estimate tool in use

Use the Budgetary "estimate" tool to give me a pre-flight token-spend estimate for this task before writing any code — show the range, scenario, and confidence:

  "Add optimistic-locking retries to the order-update endpoint."

If Budgetary says it can't confidently estimate this one ("no read"), tell me that — don't make up a number.

Actuals: estimate-only. Cursor gets the pre-flight estimate; it does not auto-report real usage back — so there's no realized number to show, and none is fabricated.

Codex

○ actuals: estimate-only

a · Onboarding — paste into the agent

Add Budgetary as an MCP server in my Codex config (~/.codex/config.toml) by appending exactly the block below.

Ask me for my Budgetary API key first (bg_test_ or bg_live_ prefix) and put it in the BUDGETARY_API_KEY value. Do not store it anywhere else or echo it back. This registers one MCP server (the "estimate" tool) and changes nothing else in my config.

[mcp_servers.budgetary]
command = "npx"
args = ["-y", "@budgetary/mcp"]

[mcp_servers.budgetary.env]
BUDGETARY_API_KEY = "bg_test_YOUR_KEY"

b · Demo — see the estimate tool in use

Call the Budgetary "estimate" tool for a pre-flight token-spend estimate on this task, and show me the range, scenario, and confidence before you do anything:

  "Migrate the config loader from JSON to TOML and keep backward compatibility."

If Budgetary returns a "no read" for this one, say so plainly instead of guessing.

Actuals: estimate-only / manual. Codex exposes no session-end event, so realized spend is never auto-captured — and never invented.

Pricing

Free, unlimited, shareware-style

Budgetary is free to use without limits. Grab a free bg_test_ key, add the MCP server, and start getting pre-flight estimates. No card, no metering games — when there's a paid tier it'll be for scale and team features, never for honest answers.

Get a free key

A bg_test_ key is ungated and free. bg_live_ keys are issued per organization for production use.