Skip to main content
Glama
tokencast

tokencast

by krulewis

CI PyPI

tokencast

Pre-execution cost estimation for LLM agent workflows. Get a cost estimate before running any agent task, then let tokencast learn from actuals to improve accuracy over time.

Available as a Claude Code plugin (recommended — one command delivers everything) or as an MCP server for Cursor, VS Code + Copilot, and Windsurf.


Installation

Install tokencast as a Claude Code plugin — delivers the MCP server, calibration hooks, and estimation skill in two commands:

/plugin marketplace add krulewis/tokencast
/plugin install tokencast@tokencast

The first command registers the tokencast marketplace. The second installs the plugin from it.

Prerequisites: uv must be installed for the MCP server to function. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

This delivers:

  • MCP server (estimate_cost, get_calibration_status, get_cost_history, report_session, report_step_cost)

  • Calibration hooks (auto-learning at session end, mid-session cost warnings, agent timeline tracking)

  • SKILL.md (estimation algorithm auto-trigger after plans)

Calibration data is stored in ~/.tokencast/calibration/ (global across projects, preserved on uninstall).

Scope options: --scope user (recommended — installs globally for all projects) or --scope project (per-project only).

Other IDEs (MCP Server)

Install the package:

pip install tokencast

Or with uvx (no install required — runs directly from PyPI):

uvx tokencast

Configure your IDE — replace /path/to/your/project with your actual project path in the config snippets below.

Cursor

Create or update .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "tokencast": {
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

VS Code + GitHub Copilot

Create or update .vscode/mcp.json in your project root:

{
  "servers": {
    "tokencast": {
      "type": "stdio",
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "tokencast": {
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Full config examples are in docs/ide-configs/.

Available tools

Once configured, tokencast exposes five MCP tools in your IDE:

Tool

What it does

estimate_cost

Estimate API cost for a planned task before running it

get_calibration_status

Check whether your estimates are well-calibrated

get_cost_history

Browse past estimates vs actuals

report_session

Report actual cost at session end to improve calibration

report_step_cost

Record the cost of a single pipeline step during a session

Example — estimate before starting work:

Estimate the cost for: size=M, files=8, complexity=high

Example — report actuals after finishing:

Report session cost: actual_cost=4.20

Related MCP server: Switchback MCP

Telemetry

tokencast includes opt-out anonymous usage telemetry. It is on by default — data is collected unless you explicitly disable it.

What is collected: session count, mean accuracy ratio, calibrated factor count, client name, framework, tool name, package version. What is NOT collected: project names, file paths, cost amounts, or any personal data.

To disable:

  • Call the disable_telemetry MCP tool (permanent opt-out, creates ~/.tokencast/no-telemetry)

  • Pass --no-telemetry to the MCP server command

  • Set TOKENCAST_TELEMETRY=0 in your environment

Precedence (highest to lowest):

  1. TOKENCAST_TELEMETRY=0 → always disables

  2. TOKENCAST_TELEMETRY=1 → always enables (overrides --no-telemetry and the no-telemetry file)

  3. ~/.tokencast/no-telemetry file exists → disables

  4. Default (no flags, no env var) → enabled

To delete your install ID: rm ~/.tokencast/install_id.

Data is sent to PostHog (US region). A random UUID is generated locally as your install ID — it contains no personal information. See the wiki for full details.


MCP Server Flags

Flag

Default

Description

--calibration-dir PATH

~/.tokencast/calibration

Where calibration data is stored

--project-dir PATH

None

Project root for file measurement

--no-telemetry

Off

Disable anonymous usage telemetry (on by default)

--version

Print version and exit


Claude Code Skill (Legacy)

The Claude Code plugin (recommended) delivers everything in one command. Use this only if you prefer the SKILL.md workflow without the plugin system.

If you use Claude Code and prefer the skill-based (SKILL.md) workflow, you can install tokencast as a Claude Code skill instead:

# Clone the repo (anywhere — it doesn't need to live inside your project)
git clone https://github.com/krulewis/tokencast.git

# Install into your project (quote paths with spaces)
bash tokencast/scripts/install-hooks.sh "/path/to/your-project"

Paths with spaces: Always wrap the project path in quotes. Without them the install script will fail on paths like /Volumes/Macintosh HD2/....

This does three things:

  1. Symlinks the skill into <project>/.claude/skills/tokencast/

  2. Adds a Stop hook for auto-learning at session end

  3. Adds a PostToolUse hook to nudge estimation after planning agents

The SKILL.md workflow is Claude Code-specific. The MCP server works in any MCP-compatible client and is the recommended path for new users.


How It Works

  1. Infers size, file count, complexity from the plan in conversation

  2. Reads reference files for pricing and token heuristics

  3. Loads learned calibration factors (if any exist)

  4. Computes per-step token estimates using activity decomposition

  5. Applies complexity multiplier, context accumulation (K+1)/2, and cache rates

  6. Splits into Optimistic / Expected / Pessimistic bands

  7. If PR Review Loop is in scope, computes loop cost using geometric decay across N review cycles

  8. Applies calibration correction to Expected band

  9. Records the estimate for later comparison with actuals

Example output:

## tokencast estimate

Change: size=M, files=5, complexity=medium
Calibration: 1.12x from 8 prior runs

| Step                  | Model  | Optimistic | Expected | Pessimistic |
|-----------------------|--------|------------|----------|-------------|
| Research Agent        | Sonnet | $0.60      | $1.17    | $4.47       |
| Architect Agent       | Opus   | $0.67      | $1.18    | $3.97       |
| ...                   | ...    | ...        | ...      | ...         |
| TOTAL                 |        | $3.37      | $6.26    | $22.64      |

Confidence Bands

Band

Cache Hit

Multiplier

Meaning

Optimistic

60%

0.6x

Best case — focused agent work

Expected

50%

1.0x

Typical run

Pessimistic

30%

3.0x

With rework loops, debugging, retries


Calibration

Calibration is fully automatic once you report actuals:

  • 0-2 sessions: No correction applied. "Collecting data" status.

  • 3-10 sessions: Global correction factor via trimmed mean of actual/expected ratios (trim_fraction=0.1).

  • 10+ sessions: EWMA with recency weighting. Per-size-class factors activate when a class has 3+ samples.

  • Outlier filtering: Sessions with actual/expected ratio >3.0x or <0.2x are excluded from calibration.

Calibration data lives in ~/.tokencast/calibration/ (gitignored, local to each user).


Python API

from tokencast import estimate_cost, report_session, report_step_cost
from tokencast import get_calibration_status, get_cost_history

# Estimate before running a task
result = estimate_cost(
    {"size": "M", "files": 5, "complexity": "medium"},
    calibration_dir="./calibration",
)

# Report actuals at session end
report_session({"actual_cost": 4.20}, calibration_dir="./calibration")

# Check calibration health
status = get_calibration_status({}, calibration_dir="./calibration")

# Browse history
history = get_cost_history({"window": "30d"}, calibration_dir="./calibration")

# Report a single step's cost
report_step_cost(
    {"step_name": "Research Agent", "cost": 0.85},
    calibration_dir="./calibration",
)

Manual Invocation (Skill mode)

In Claude Code with SKILL.md installed, you can invoke explicitly:

/tokencast size=L files=12 complexity=high
/tokencast steps=implement,test,qa
/tokencast review_cycles=3
/tokencast review_cycles=0

Files

SKILL.md                        — Skill definition (auto-trigger, algorithm)
references/pricing.md           — Model prices, cache rates, step→model map
references/heuristics.md        — Token budgets, pipeline decompositions, multipliers
references/examples.md          — Worked examples with arithmetic
references/calibration-algorithm.md — Detailed calibration algorithm reference
docs/ide-configs/               — Per-IDE MCP config examples
src/tokencast/                  — Core estimation engine (Python package)
src/tokencast_mcp/              — MCP server (Python package)
scripts/
  install-hooks.sh              — One-time project setup (skill mode)
  disable.sh                    — Remove from project (skill mode)
  tokencast-learn.sh            — Stop hook: auto-captures actuals (skill mode)
  tokencast-track.sh            — PostToolUse hook: nudges estimation after plans
  sum-session-tokens.py         — Parses session JSONL for actual costs
  update-factors.py             — Computes calibration factors from history
calibration/                    — Per-user local data (gitignored)
  history.jsonl                 — Estimate vs actual records
  factors.json                  — Learned correction factors
  active-estimate.json          — Transient marker for current estimate

Limitations

  • Pipeline step names reflect a default workflow — map your own steps to the closest defaults. Formulas are pipeline-agnostic (see references/heuristics.md)

  • Heuristics assume typical 150-300 line source files

  • Calibration requires 3+ completed sessions before corrections activate

  • Pricing data embedded; check last_updated in references/pricing.md

  • Multi-session tasks only capture the session containing the estimate


License

MIT

Available Tools

6 tools
disable_telemetryA

Permanently disable anonymous telemetry. Creates ~/.tokencast/no-telemetry file. Use this to opt out of usage data collection.

Inputs: no named parameters.

estimate_costB

Estimate Anthropic API token costs for a development plan before execution

Inputs: size (required), files (required), complexity (required), steps, +6 more.

get_calibration_statusB

Get calibration health and accuracy metrics for cost estimates

Inputs: window.

get_cost_historyC

Query historical cost estimation records and actuals

Inputs: window, include_outliers.

report_sessionC

Report actual session cost to improve future calibration

Inputs: actual_cost (required), turn_count, step_actuals, review_cycles_actual.

report_step_costA

Record the cost of a completed pipeline step. Costs accumulate per step and are flushed when report_session is called.

Inputs: step_name (required), cost, model, tokens_in, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct concern: telemetry opt-out, cost estimation, calibration metrics, historical queries, and cost reporting at different granularities. No two tools overlap in purpose or action.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in lowercase snake_case (disable_telemetry, estimate_cost, get_calibration_status, get_cost_history, report_session, report_step_cost). The naming style is uniform and predictable.

    Tool Count5/5

    Six tools is well-scoped for a cost estimation and calibration server. Each tool contributes a necessary function without redundant or bloated additions.

    Completeness4/5

    The toolset covers the essential workflow: estimate costs, report actuals, inspect calibration, and query history. Minor gaps exist (e.g., no way to enable telemetry after disabling, no per-estimate detail retrieval), but they do not break the core usage flow.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Estimates, compares, and controls LLM API costs before agents spend tokens, with tools for cost estimation, model comparison, and budget checking.
      59 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables monitoring of running agent loops with token and monetary cost estimation, pruning of verbose thinking chains near limits, and routing sub-tasks between fast/cheap and deep reasoning models. It provides deterministic, MCP-compatible budget optimization for autonomous agents and copilot frameworks.
      MIT