{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/tokencast-logo.svg\" alt=\"tokencast logo\" width=\"150\">\n</p>\n\n[![CI](https://github.com/krulewis/tokencast/actions/workflows/ci.yml/badge.svg)](https://github.com/krulewis/tokencast/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/tokencast)](https://pypi.org/project/tokencast/)\n\n<!-- mcp-name: io.github.krulewis/tokencast -->\n\n# tokencast\n\nPre-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.\n\nAvailable as a **Claude Code plugin** (recommended — one command delivers everything) or as an **MCP server** for Cursor, VS Code + Copilot, and Windsurf.\n\n---\n\n## Installation\n\n### Claude Code (Recommended)\n\nInstall tokencast as a Claude Code plugin — delivers the MCP server, calibration hooks, and estimation skill in two commands:\n\n```\n/plugin marketplace add krulewis/tokencast\n/plugin install tokencast@tokencast\n```\n\nThe first command registers the tokencast marketplace. The second installs the plugin\nfrom it.\n\n> **Prerequisites:** [`uv`](https://docs.astral.sh/uv/) must be installed for the MCP server to function.\n> Install with: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n\nThis delivers:\n- **MCP server** (`estimate_cost`, `get_calibration_status`, `get_cost_history`, `report_session`, `report_step_cost`)\n- **Calibration hooks** (auto-learning at session end, mid-session cost warnings, agent timeline tracking)\n- **SKILL.md** (estimation algorithm auto-trigger after plans)\n\nCalibration data is stored in `~/.tokencast/calibration/` (global across projects, preserved on uninstall).\n\n> **Scope options:** `--scope user` (recommended — installs globally for all projects) or `--scope project` (per-project only).\n\n### Other IDEs (MCP Server)\n\nInstall the package:\n\n```bash\npip install tokencast\n```\n\nOr with `uvx` (no install required — runs directly from PyPI):\n\n```bash\nuvx tokencast\n```\n\nConfigure your IDE — replace `/path/to/your/project` with your actual project path in the config snippets below.\n\n#### Cursor\n\nCreate or update `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokencast\": {\n      \"command\": \"tokencast-mcp\",\n      \"args\": [\n        \"--calibration-dir\", \"/path/to/your/project/calibration\",\n        \"--project-dir\", \"/path/to/your/project\"\n      ]\n    }\n  }\n}\n```\n\n#### VS Code + GitHub Copilot\n\nCreate or update `.vscode/mcp.json` in your project root:\n\n```json\n{\n  \"servers\": {\n    \"tokencast\": {\n      \"type\": \"stdio\",\n      \"command\": \"tokencast-mcp\",\n      \"args\": [\n        \"--calibration-dir\", \"/path/to/your/project/calibration\",\n        \"--project-dir\", \"/path/to/your/project\"\n      ]\n    }\n  }\n}\n```\n\n#### Windsurf\n\nAdd to your Windsurf MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokencast\": {\n      \"command\": \"tokencast-mcp\",\n      \"args\": [\n        \"--calibration-dir\", \"/path/to/your/project/calibration\",\n        \"--project-dir\", \"/path/to/your/project\"\n      ]\n    }\n  }\n}\n```\n\nFull config examples are in [`docs/ide-configs/`](docs/ide-configs/).\n\n#### Available tools\n\nOnce configured, tokencast exposes five MCP tools in your IDE:\n\n| Tool | What it does |\n|------|-------------|\n| `estimate_cost` | Estimate API cost for a planned task before running it |\n| `get_calibration_status` | Check whether your estimates are well-calibrated |\n| `get_cost_history` | Browse past estimates vs actuals |\n| `report_session` | Report actual cost at session end to improve calibration |\n| `report_step_cost` | Record the cost of a single pipeline step during a session |\n\n**Example — estimate before starting work:**\n```\nEstimate the cost for: size=M, files=8, complexity=high\n```\n\n**Example — report actuals after finishing:**\n```\nReport session cost: actual_cost=4.20\n```\n\n---\n\n## Telemetry\n\ntokencast includes **opt-out** anonymous usage telemetry. It is **on by default** — data is collected unless you explicitly disable it.\n\n**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.\n\n**To disable:**\n- Call the `disable_telemetry` MCP tool (permanent opt-out, creates `~/.tokencast/no-telemetry`)\n- Pass `--no-telemetry` to the MCP server command\n- Set `TOKENCAST_TELEMETRY=0` in your environment\n\n**Precedence (highest to lowest):**\n1. `TOKENCAST_TELEMETRY=0` → always disables\n2. `TOKENCAST_TELEMETRY=1` → always enables (overrides `--no-telemetry` and the no-telemetry file)\n3. `~/.tokencast/no-telemetry` file exists → disables\n4. Default (no flags, no env var) → enabled\n\nTo delete your install ID: `rm ~/.tokencast/install_id`.\n\nData is sent to [PostHog](https://posthog.com) (US region). A random UUID is generated locally as your install ID — it contains no personal information. See the [wiki](https://github.com/krulewis/tokencast/wiki/Configuration#telemetry) for full details.\n\n---\n\n## MCP Server Flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--calibration-dir PATH` | `~/.tokencast/calibration` | Where calibration data is stored |\n| `--project-dir PATH` | None | Project root for file measurement |\n| `--no-telemetry` | Off | Disable anonymous usage telemetry (on by default) |\n| `--version` | | Print version and exit |\n\n---\n\n## Claude Code Skill (Legacy)\n\nThe Claude Code plugin (recommended) delivers everything in one command. Use this only if you prefer the SKILL.md workflow without the plugin system.\n\nIf you use Claude Code and prefer the skill-based (SKILL.md) workflow, you can install tokencast as a Claude Code skill instead:\n\n```bash\n# Clone the repo (anywhere — it doesn't need to live inside your project)\ngit clone https://github.com/krulewis/tokencast.git\n\n# Install into your project (quote paths with spaces)\nbash tokencast/scripts/install-hooks.sh \"/path/to/your-project\"\n```\n\n> **Paths with spaces:** Always wrap the project path in quotes. Without them the install script will fail on paths like `/Volumes/Macintosh HD2/...`.\n\nThis does three things:\n1. Symlinks the skill into `<project>/.claude/skills/tokencast/`\n2. Adds a `Stop` hook for auto-learning at session end\n3. Adds a `PostToolUse` hook to nudge estimation after planning agents\n\nThe SKILL.md workflow is Claude Code-specific. The MCP server works in any MCP-compatible client and is the recommended path for new users.\n\n---\n\n## How It Works\n\n1. Infers size, file count, complexity from the plan in conversation\n2. Reads reference files for pricing and token heuristics\n3. Loads learned calibration factors (if any exist)\n4. Computes per-step token estimates using activity decomposition\n5. Applies complexity multiplier, context accumulation `(K+1)/2`, and cache rates\n6. Splits into Optimistic / Expected / Pessimistic bands\n7. If PR Review Loop is in scope, computes loop cost using geometric decay across N review cycles\n8. Applies calibration correction to Expected band\n9. Records the estimate for later comparison with actuals\n\n**Example output:**\n\n```\n## tokencast estimate\n\nChange: size=M, files=5, complexity=medium\nCalibration: 1.12x from 8 prior runs\n\n| Step                  | Model  | Optimistic | Expected | Pessimistic |\n|-----------------------|--------|------------|----------|-------------|\n| Research Agent        | Sonnet | $0.60      | $1.17    | $4.47       |\n| Architect Agent       | Opus   | $0.67      | $1.18    | $3.97       |\n| ...                   | ...    | ...        | ...      | ...         |\n| TOTAL                 |        | $3.37      | $6.26    | $22.64      |\n```\n\n---\n\n## Confidence Bands\n\n| Band        | Cache Hit | Multiplier | Meaning                                |\n|-------------|-----------|------------|----------------------------------------|\n| Optimistic  | 60%       | 0.6x       | Best case — focused agent work         |\n| Expected    | 50%       | 1.0x       | Typical run                            |\n| Pessimistic | 30%       | 3.0x       | With rework loops, debugging, retries  |\n\n---\n\n## Calibration\n\nCalibration is fully automatic once you report actuals:\n- **0-2 sessions:** No correction applied. \"Collecting data\" status.\n- **3-10 sessions:** Global correction factor via trimmed mean of actual/expected ratios (trim_fraction=0.1).\n- **10+ sessions:** EWMA with recency weighting. Per-size-class factors activate when a class has 3+ samples.\n- **Outlier filtering:** Sessions with actual/expected ratio >3.0x or <0.2x are excluded from calibration.\n\nCalibration data lives in `~/.tokencast/calibration/` (gitignored, local to each user).\n\n---\n\n## Python API\n\n```python\nfrom tokencast import estimate_cost, report_session, report_step_cost\nfrom tokencast import get_calibration_status, get_cost_history\n\n# Estimate before running a task\nresult = estimate_cost(\n    {\"size\": \"M\", \"files\": 5, \"complexity\": \"medium\"},\n    calibration_dir=\"./calibration\",\n)\n\n# Report actuals at session end\nreport_session({\"actual_cost\": 4.20}, calibration_dir=\"./calibration\")\n\n# Check calibration health\nstatus = get_calibration_status({}, calibration_dir=\"./calibration\")\n\n# Browse history\nhistory = get_cost_history({\"window\": \"30d\"}, calibration_dir=\"./calibration\")\n\n# Report a single step's cost\nreport_step_cost(\n    {\"step_name\": \"Research Agent\", \"cost\": 0.85},\n    calibration_dir=\"./calibration\",\n)\n```\n\n---\n\n## Manual Invocation (Skill mode)\n\nIn Claude Code with SKILL.md installed, you can invoke explicitly:\n\n```\n/tokencast size=L files=12 complexity=high\n/tokencast steps=implement,test,qa\n/tokencast review_cycles=3\n/tokencast review_cycles=0\n```\n\n---\n\n## Files\n\n```\nSKILL.md                        — Skill definition (auto-trigger, algorithm)\nreferences/pricing.md           — Model prices, cache rates, step→model map\nreferences/heuristics.md        — Token budgets, pipeline decompositions, multipliers\nreferences/examples.md          — Worked examples with arithmetic\nreferences/calibration-algorithm.md — Detailed calibration algorithm reference\ndocs/ide-configs/               — Per-IDE MCP config examples\nsrc/tokencast/                  — Core estimation engine (Python package)\nsrc/tokencast_mcp/              — MCP server (Python package)\nscripts/\n  install-hooks.sh              — One-time project setup (skill mode)\n  disable.sh                    — Remove from project (skill mode)\n  tokencast-learn.sh            — Stop hook: auto-captures actuals (skill mode)\n  tokencast-track.sh            — PostToolUse hook: nudges estimation after plans\n  sum-session-tokens.py         — Parses session JSONL for actual costs\n  update-factors.py             — Computes calibration factors from history\ncalibration/                    — Per-user local data (gitignored)\n  history.jsonl                 — Estimate vs actual records\n  factors.json                  — Learned correction factors\n  active-estimate.json          — Transient marker for current estimate\n```\n\n---\n\n## Limitations\n\n- Pipeline step names reflect a default workflow — map your own steps to the closest defaults. Formulas are pipeline-agnostic (see `references/heuristics.md`)\n- Heuristics assume typical 150-300 line source files\n- Calibration requires 3+ completed sessions before corrections activate\n- Pricing data embedded; check `last_updated` in references/pricing.md\n- Multi-session tasks only capture the session containing the estimate\n\n---\n\n## License\n\nMIT\n",
  "bytes": 11462,
  "sha": "76bcce35d558970dc68ca7ad1bdccdd7ad15136439396655bdb823ef5c9bd59b",
  "repo_slug": "krulewis/tokencast",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_krulewis_tokencast_7abf766f/readme"
}