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 --transport http budgetary https://api.budgetary.tools/mcp \
  --header "Authorization: Bearer bg_test_YOUR_KEY"

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.

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).

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

TODO(verify): exact Open VSX / Marketplace extension id not yet pinned in source.

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
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" pointing at the hosted API:
   claude mcp add --transport http budgetary https://api.budgetary.tools/mcp --header "Authorization: Bearer <the key I gave you>"

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. Once installed, Claude Code captures your real session token usage and lines it up against the estimate.

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" }
    }
  }
}

TODO(verify): config derived from the MCP registry package; not yet confirmed against an official Cursor setup doc.

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"]
env = { BUDGETARY_API_KEY = "bg_test_YOUR_KEY" }

TODO(verify): config derived from the MCP registry package; not yet confirmed against an official Codex setup doc.

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 See it live at dryruns.tools →

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