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

Claude Code (Recommended)

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

Telemetry

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

**What is collect

... View full README on GitHub