Tokenscope

tokenscope ⏣

AI コーディングセッションで実際にいくらかかったのか、そしてコンテキストを何が消費しているのかを確認できます。 Claude Code のセッションログを解析し、コストの内訳を表示する、ローカルで読み取り専用の CLI です。モデルの出力と、毎ターン再送されるコンテキスト（多くの請求額の隠れた 60% 以上）を確認できます。

$ npx @wartzar-bee/tokenscope

  tokenscope ⏣  latest session
  ──────────────────────────────────────────────────────
  Total cost   $868.84   over 967 model turns

  Where the money went
  output (model writing)     ████░░░░░░░░░░░░░░░░░░░░  16%  $137.24
  cache read (re-sent ctx)   ████████████████░░░░░░░░  66%  $577.59
  cache write (new ctx)      ████░░░░░░░░░░░░░░░░░░░░  18%  $153.67

  Context size per turn  (peak 822k · avg 404k · now 822k tokens)
  ▁▁▁▁▁▂▂▂▂▂▂▂▃▃▃▃▃▃▃▄▄▄▄▄▅▅▅▅▅▆▆▆▆▇▇▇▇▇▇█

  Insights
  • Re-sent (cached) context cost $577.59 (66% of spend) — context re-read every turn.
  • Peak context ~822k tokens — /compact or a fresh session would cut per-turn cost.
  • Only 16% of spend is the model's actual output.

(実際のセッションをデフォルトの Opus 料金で表示しています。料金は変更できるため、数値は異なります。)

その理由

エージェント型コーディング（Claude Code など）では、思いがけない請求が発生します。その原因は単純です。セッションが長くなるにつれて、コンテキスト全体が毎ターン再送されるため、モデルの出力が少なくてもコストが膨らみます。既存のダッシュボードが示すのは合計ですが、tokenscope はコストの内訳を示します。出力、キャッシュ読み取り、キャッシュ書き込み、新規入力の内訳、ターンごとのコンテキスト増加曲線、モデル別コスト、サブエージェントの使用額、コンテキストを埋めているツールに加え、具体的な「ここを削る」ためのヒントも確認できます。

10 秒で試す（Claude Code のログは不要）

npx @wartzar-bee/tokenscope --demo

付属のサンプルセッションで動作するため、自分のログを指定する前に完全なレポートを確認できます。セットアップも設定も不要です。（サンプルはデモ用の合成データです。）

インストール／実行

インストール不要です。npx で実行できます。

npx @wartzar-bee/tokenscope               # your most recent Claude Code session
npx @wartzar-bee/tokenscope --demo        # a bundled sample session — no logs needed
npx @wartzar-bee/tokenscope --all         # aggregate every session
npx @wartzar-bee/tokenscope <file|dir>    # a specific session .jsonl
npx @wartzar-bee/tokenscope --version     # print the installed version and exit
npx @wartzar-bee/tokenscope --json        # machine-readable
npx @wartzar-bee/tokenscope --share       # privacy-safe shareable summary (markdown + SVG card)
npx @wartzar-bee/tokenscope --share-svg   # just the SVG "cost report card"
npx @wartzar-bee/tokenscope scan          # static token footprint of a source dir (the engine behind ci-guardrail)
npx @wartzar-bee/tokenscope scan --diff ../base   # cost delta of the current dir vs a base dir — catch a regression before you push
npx @wartzar-bee/tokenscope scan --max-total 50000            # exit 1 if the footprint exceeds a budget — a local cost gate
npx @wartzar-bee/tokenscope scan --diff ../base --max-delta 2000   # exit 1 if the diff adds more than N tokens

~/.claude/projects/**/*.jsonl を読み込みます。読み取り専用、ローカル動作、ネットワーク通信なし、テレメトリーなしです。ソースコードを確認できます。マシンの外にデータが送信されることはありません。

ローカルのコストゲート（プッシュ前／コミット前）

--max-total N／--max-delta N を指定すると、トークン使用量（または差分の増加量）が予算を超えた場合に scan が 終了コード 1 で終了します。CI で ci-guardrail が実行するのと同じチェックを、プッシュ前にローカルで行えます。絶対予算を git フックに組み込めば、暴走したプロンプト／設定がマシンの外に出るのを防げます。

# .git/hooks/pre-push  (chmod +x)
npx -y @wartzar-bee/tokenscope scan --dir prompts --max-total 50000 \
  || { echo "prompt token footprint over budget — trim before pushing"; exit 1; }

予算内ならレポートを表示して終了コード 0 で終了し、予算を超えた場合は BLOCKED: の行を表示して終了コード 1 で終了します。--max-* フラグがない場合、scan はレポートを表示するだけ（終了コード 0）なので、必要な場合のみ有効になります。--max-delta はディスク上の 2 つのディレクトリ間の差分をチェックします（scan --diff <baseDir> --max-delta N）。絶対上限ではなく回帰チェックをしたい場合は、チェックアウト済みのベースツリーを指定してください。

pre-commit フレームワークを使っていますか？git フックのスクリプトを書くことなく、tokenscope を .pre-commit-config.yaml に追加できます。

repos:
  - repo: https://github.com/wartzar-bee/tokenscope
    rev: v0.2.6
    hooks:
      - id: tokenscope
        args: ["--dir", "prompts", "--max-total", "50000"]   # optional — omit to just report

language: node で、依存関係はゼロです。args を指定しない場合は使用量を表示して終了コード 0 で終了します。予算超過時にコミットを失敗させるには、--max-total N（または --diff <baseDir> --max-delta N）を追加してください。

請求額を共有する（プライバシーに配慮）

--share は集計値のみから作成したコンパクトなサマリーを出力するため、公開の場に安全に貼り付けられます。ファイルパスやプロンプト／応答の内容は含まれません。

• Reddit／Discord／GitHub の issue に貼り付けられるMarkdown（合計、出力／キャッシュ読み取り／キャッシュ書き込み／新規入力の割合（%）、コンテキストのピーク値／平均値、および「使用額の X% は再送されたコンテキスト」という要点）。
• 単体で使える SVG「コストレポートカード」（--share-svg）。バイナリ依存関係はなく、GitHub 上でインライン表示でき、簡単に共有できます。
• 比較結果 — どちらの形式でも、実際のセッションを収録した同梱のオフライン参照データセットを基準に、「自分のセッションは珍しいか？」がわかります（例：「測定対象のセッションの約 80% よりキャッシュ効率が高く、セッションの再送率の中央値は 24%」）。これは比較の目安であり、全数調査ではありません。完全な分布は tokenscope.pages.dev/benchmark をご覧ください。

ターミナルのフラグを使いたくない場合は、web/ のウェブ画面で同じレポートをすべてブラウザー内で生成できます。--json の出力を貼り付けると、完全なレポートと SVG カードがローカルで生成されます。データはアップロードされません。

AI エージェントから使う（MCP サーバー）

同じエンジンを AI エージェント／MCP クライアント（Claude Desktop、Claude Code など）にツールとして公開する MCP サーバー があります。利用できるツールは analyze_claude_cost、get_cost_benchmark、tokenscope_share_summary です。MCP の設定に追加してください。

{ "mcpServers": { "tokenscope": { "command": "npx", "args": ["-y", "@wartzar-bee/tokenscope-mcp"] } } }

次に、エージェントに 「tokenscope を使って、直近の Claude Code セッションを分析して」 と頼んでください。同じローカルの読み取り専用エンジンです。詳しくは mcp/README.md をご覧ください。

料金

ドキュメントに記載されているデフォルト料金を使用します（Anthropic のキャッシュ倍率：書き込みは入力の 1.25×／2×、読み取りは入力の 0.1×）。正確なモデル／ティアに合わせて、./.tokenscope.json で確認して上書きしてください。

{ "pricing": { "claude-opus-4": { "in": 15, "out": 75 } } }

不明なモデルにはフラグが付けられます（$0 として暗黙に計上されることはありません）。トークン数はログから直接読み取られ、コストはその数に表示価格を掛けて算出されます。

wartzar-bee のコストツールキットの一部

tokenscope は姉妹ツールを支える計測エンジンであり、3 つあるオープンソースのコストプロジェクトの 1 つです。

• ci-guardrail — CI で tokenscope を実行し、プルリクエストによるトークンコストの増減を予測して、原因となるファイルについてコメントする GitHub Action です（レポートのみ、またはしきい値を超えた場合にビルドを失敗させます）：uses: wartzar-bee/ci-guardrail@v1。
• enclave — wartzar-bee のエージェント群が実行される、セキュリティを最優先したセルフホスト可能なランタイムおよびサンドボックスです（Apache-2.0）。

tokenscope が役に立ったら、ci-guardrail を使えば、設定不要であらゆる PR 上で実行できます。

このツールが生まれた理由 — 詳細

tokenscope は、自律型エージェントを稼働させ、請求額を目の当たりにした経験から生まれました。その背景となった記事はこちらです。

• エージェントをタイマーで動かしたら、一晩でほとんど何もせずに 1 億 3,600 万トークンを消費した — この取り組みのきっかけとなった、コストの暴走に関する事後分析です。
• Claude Code の料金は実際どこにかかるのか — 自分の 66 セッションを計測した — tokenscope が自動化する、実測に基づく内訳です。
• Claude Code のコスト計算式：同じセッションでも翌日にはコストが 10 倍になる理由 — tokenscope が明らかにするコストの仕組みです。
• コスト監査シリーズ — 人気のエージェントフレームワーク（LangChain、AutoGen、CrewAI、…）を対象とした、再現可能なトークンコスト監査です。
• リリース前に CI でトークンコストのリグレッションを検出する — PR のコストゲートとして GitHub Action から tokenscope を使う方法です。

ステータス／ロードマップ

• v0.1：Claude Code セッションのコスト、コンテキストの帰属分析、インサイト。コスト計算のユニットテスト 20 件すべてに合格（npm test）。
• 次の予定（エビデンスに基づいて決定）：ツール／ファイルごとのトークン帰属分析、日次／予算アラート、--watch によるライブメーター、OpenAI／Codex のログ対応。

MIT。Anthropic とは提携していません。