tokencast

tokencast

LLM エージェントのワークフローを実行する前にコストを見積もります。エージェントのタスクを実行する前にコストを見積もり、その後 tokencast が実際のコストから学習して、時間とともに精度を向上させます。

Claude Code プラグイン（推奨。1 つのコマンドですべてを導入できます）または、Cursor、VS Code + Copilot、Windsurf 向けの MCP サーバーとして利用できます。

---

インストール

Claude Code（推奨）

tokencast を Claude Code プラグインとしてインストールします。MCP サーバー、キャリブレーションフック、見積もりスキルを 2 つのコマンドで導入できます。

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

最初のコマンドで tokencast マーケットプレイスを登録します。2 つ目のコマンドで、そこからプラグインをインストールします。

前提条件： MCP サーバーを動作させるには、uv がインストールされている必要があります。 次のコマンドでインストールします：curl -LsSf https://astral.sh/uv/install.sh | sh

以下が導入されます：

• MCP サーバー（estimate_cost、get_calibration_status、get_cost_history、report_session、report_step_cost）
• キャリブレーションフック（セッション終了時の自動学習、セッション中のコスト警告、エージェントのタイムライン追跡）
• SKILL.md（プラン作成後に自動で起動する見積もりアルゴリズム）

キャリブレーションデータは ~/.tokencast/calibration/ に保存されます（全プロジェクト共通で、アンインストール後も保持されます）。

スコープの選択肢： --scope user（推奨。すべてのプロジェクトにグローバルにインストール）または --scope project（プロジェクトごとにインストール）。

その他の IDE（MCP サーバー）

パッケージをインストールします：

pip install tokencast

または uvx を使用します（インストール不要。PyPI から直接実行します）。

uvx tokencast

IDE を設定します。以下の設定例の /path/to/your/project を、実際のプロジェクトパスに置き換えてください。

Cursor

プロジェクトのルートにある .cursor/mcp.json を作成または更新します：

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

VS Code + GitHub Copilot

プロジェクトのルートにある .vscode/mcp.json を作成または更新します：

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

Windsurf

Windsurf の MCP 設定に追加します：

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

設定の完全な例は docs/ide-configs/ にあります。

利用可能なツール

設定すると、tokencast は IDE で 5 つの MCP ツールを利用できるようにします：

ツール	機能
estimate_cost	タスクを実行する前に、計画したタスクの API コストを見積もります
get_calibration_status	見積もりが適切にキャリブレーションされているか確認します
get_cost_history	過去の見積もりと実際のコストを確認します
report_session	キャリブレーションの精度を高めるため、セッション終了時に実際のコストを報告します
report_step_cost	セッション中に、パイプラインの個々のステップのコストを記録します

例 — 作業開始前に見積もる：

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

例 — 完了後に実際のコストを報告する：

Report session cost: actual_cost=4.20

---

テレメトリー

tokencast には、匿名の使用状況テレメトリーをオプトアウトする機能があります。デフォルトで有効になっており、明示的に無効にしない限りデータが収集されます。

**収集されるデータ：**セッション数、平均精度比、キャリブレーション係数の数、クライアント名、フレームワーク、ツール名、パッケージのバージョン。**収集されないデータ：**プロジェクト名、ファイルパス、コストの金額、個人データ。

無効にする方法：

• disable_telemetry MCP ツールを呼び出す（恒久的にオプトアウトし、~/.tokencast/no-telemetry を作成します）
• MCP サーバーのコマンドに --no-telemetry を渡す
• 環境変数に TOKENCAST_TELEMETRY=0 を設定する

優先順位（高い順）：

1. TOKENCAST_TELEMETRY=0 → 常に無効
2. TOKENCAST_TELEMETRY=1 → 常に有効（--no-telemetry と no-telemetry ファイルを上書きします）
3. ~/.tokencast/no-telemetry ファイルが存在する → 無効
4. デフォルト（フラグも環境変数もなし） → 有効

インストール ID を削除するには、rm ~/.tokencast/install_id を実行します。

データは PostHog（米国リージョン）に送信されます。ランダムな UUID がインストール ID としてローカルで生成され、個人情報は含まれません。詳細はWikiをご覧ください。

---

MCP サーバーのフラグ

フラグ	デフォルト	説明
--calibration-dir PATH	~/.tokencast/calibration	キャリブレーションデータの保存先
--project-dir PATH	なし	ファイル計測に使用するプロジェクトのルート
--no-telemetry	オフ	匿名の使用状況テレメトリーを無効にします（デフォルトでは有効）
--version		バージョンを表示して終了

---

Claude Code スキル（レガシー）

Claude Code プラグイン（推奨）を使えば、すべてを 1 つのコマンドで利用できます。プラグインシステムを使わず、SKILL.md のワークフローを使いたい場合にのみ、こちらを使用してください。

Claude Code を使っていて、スキルベース（SKILL.md）のワークフローを希望する場合は、代わりに tokencast を Claude Code スキルとしてインストールできます。

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

**スペースを含むパス：**プロジェクトのパスは必ず引用符で囲んでください。囲まないと、/Volumes/Macintosh HD2/... のようなパスでインストールスクリプトが失敗します。

次の 3 つを実行します。

1. スキルを <project>/.claude/skills/tokencast/ にシンボリックリンクします
2. セッション終了時に自動学習するための Stop フックを追加します
3. 計画エージェントの後に見積もりを促す PostToolUse フックを追加します

SKILL.md のワークフローは Claude Code 専用です。MCP サーバーは MCP 互換のあらゆるクライアントで動作し、新規ユーザーに推奨される方法です。

---

仕組み

1. 会話内の計画から、規模、ファイル数、複雑さを推定します
2. 料金設定とトークンのヒューリスティックに関する参照ファイルを読み込みます
3. 学習済みのキャリブレーション係数があれば読み込みます
4. アクティビティの分解を使って、各ステップのトークン数を見積もります
5. 複雑さの乗数、コンテキストの累積 (K+1)/2、キャッシュ率を適用します
6. 楽観・期待・悲観の幅に分けます
7. PR Review Loop が対象範囲に含まれる場合、N 回のレビューサイクルにわたる幾何減衰を使ってループのコストを計算します
8. 期待値の幅にキャリブレーション補正を適用します
9. 実績と後で比較できるよう、見積もりを記録します

出力例：

## 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      |

---

信頼度の幅

幅	キャッシュヒット率	乗数	意味
楽観	60%	0.6x	最良のケース — 集中して作業するエージェント
期待	50%	1.0x	一般的な実行
悲観	30%	3.0x	手戻りループ、デバッグ、再試行を含む

---

キャリブレーション

実績を報告すると、キャリブレーションは完全に自動で行われます。

• 0～2 セッション： 補正は適用されません。「データ収集中」のステータスです。
• 3～10 セッション： 実績／予測比のトリム平均（trim_fraction=0.1）による全体の補正係数が適用されます。
• 10 セッション以上： 直近のデータを重視した EWMA が適用されます。サイズクラスごとのサンプルが 3 件以上になると、そのクラスの係数が有効になります。
• 外れ値の除外： 実績／予測比が 3.0 倍を超える、または 0.2 倍を下回るセッションはキャリブレーションから除外されます。

キャリブレーションデータは ~/.tokencast/calibration/ に保存されます（gitignore 対象で、ユーザーごとにローカルに保存されます）。

---

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",
)

---

手動での実行（スキルモード）

SKILL.md をインストールした Claude Code では、明示的に次のように実行できます。

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

---

ファイル

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

---

制限事項

• パイプラインのステップ名はデフォルトのワークフローを反映しています。独自のステップは、最も近いデフォルトのステップに対応付けてください。数式はパイプラインに依存しません（references/heuristics.md を参照）。
• ヒューリスティクスは、一般的な 150～300 行のソースファイルを想定しています。
• 補正が有効になるには、完了したセッションが 3 件以上必要です。
• 料金データは埋め込み式です。references/pricing.md の last_updated を確認してください。
• 複数セッションにまたがるタスクでは、見積もりを行ったセッションのみが記録されます。

---

ライセンス

MIT