メインコンテンツへ移動
AIチュートリアル

tokentabでローカルAIのトークン使用量とコストを追跡

tokentabのインストール方法、ローカルのセッションログからAIトークンの使用量と推定コストを分析する方法、日付やプロジェクトでレポートを絞り込む方法、非公開のWebダッシュボードを開く方法、結果の解釈方法、別のプロバイダーを追加してプロジェクトを拡張する方法を解説します。

約12分で読了
tokentabでローカルAIのトークン使用量とコストを追跡

tokentabの機能

tokentabは、コーディングアシスタントがトークンをどのように消費し、推定コストをどのように積み上げているかを把握するためのローカルレポートツールです。対応ツールがすでにコンピューター上に保存しているセッションログを読み込み、モデル、プロバイダー、プロジェクト、日付、推定されるアクティビティの種類ごとに使用状況を分類します。

アカウントやAPIキーは必要ありません。処理はお使いのマシン上で完結し、tokentabがセッション情報をアップロードしたり、料金情報サービスに接続したりすることはありません。

tokentabのウェブダッシュボード

対応ツールとログの保存場所

tokentabには現在、3つのツール用の動作するパーサーが含まれています。

  • Claude Code: ~/.claude/projects/**/*.jsonl
  • Codex: ~/.codex/sessions/**/rollout-*.jsonl
  • Gemini CLI: ~/.gemini/tmp/**/session-*.json

Cursor用のプロバイダースロットは存在しますが、パーサーはまだ完成していません。対応ツールがインストールされていない場合、tokentabはそのツールを単にスキップします。そのため、レポートにはお使いのマシン上でログを利用できるツールのみが含まれます。

主な機能

  • 既存のローカルセッションログからトークン数を直接読み取る。
  • ローカルで管理する料金表を使ってコストを推定する。
  • プロバイダー、モデル、プロジェクト、日付、アクティビティごとにデータを分類する。
  • 日次、月次、全期間、カスタム日付範囲に対応する。
  • ターミナルテーブルまたは機械可読なJSONを生成する。
  • localhostのみにバインドするブラウザダッシュボードを提供する。
  • 出力がパイプに渡されると、ターミナルカラーを自動的に削除する。
  • ウェブフレームワークを使わず、Python標準ライブラリのHTTPサーバーでダッシュボードを実行する。

唯一のサードパーティ依存関係は、ターミナルテーブルを描画するRichです。解析、JSON処理、ローカルウェブサーバーにはPython標準ライブラリを使用します。

tokentabをインストールする

標準インストール

リポジトリをクローンしてディレクトリに移動し、現在有効なPython環境にパッケージをインストールします。

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install .
python cli.py

インストールすると、パスにtokentabコマンドが追加されます。その後は、インストール済みのコマンドを直接実行できます。

tokentab

編集可能なソースインストール

コードを確認または変更する予定がある場合は、編集可能モードでインストールします。

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install -e .
tokentab

編集可能インストールでは、コマンドが作業コピーに接続されたままになるため、パッケージを再インストールしなくてもローカルコードの変更が反映されます。

最初のレポートを実行する

リポジトリのディレクトリから、オプションなしでCLIを実行します。

python cli.py

デフォルトのレポートでは、検出されたすべてのプロバイダーとプロジェクトについて、過去7日間を対象にします。コマンドをインストールした場合は、次のように実行できます。

tokentab

tokentabはプロバイダーが既に使用しているログディレクトリを読み込むため、アカウント設定や認証情報の構成は必要ありません。対応するログが存在しない場合、その使用状況は含まれません。

時間で使用状況を絞り込む

今日のアクティビティ

python cli.py -today

現在の暦月

python cli.py -month

利用可能な全履歴

python cli.py -p all

特定の日付範囲

python cli.py --from 2026-06-01 --to 2026-06-15

カスタム範囲は、使用状況をスプリント、請求期間、実験、その他の指定した期間と照合したい場合に便利です。

プロバイダーまたはプロジェクトで絞り込む

Claudeの使用状況だけを表示するには、プロバイダーフィルターを指定します。

python cli.py --provider claude

1つのプロジェクトに絞り込むには、プロジェクト名を使用します。

python cli.py --project myapp

これらのフィルターを使うと、特定のコードベースやツールのコストを全体のアクティビティから分けて確認できます。

機械可読なJSONをエクスポートする

別のプログラムでレポートを利用する場合は、--jsonを使用します。

python cli.py --json

たとえばjqがインストールされている場合は、JSONをパイプで渡して整形や追加処理を行えます。

python cli.py --json | jq .

tokentabは通常の出力がパイプに渡されると、ターミナルカラーを自動的に削除します。これにより、ANSIエスケープコードなしでレポートをプルリクエスト、チャットメッセージ、ファイル、その他のコマンドに貼り付けやすくなります。

ローカルウェブダッシュボードを使う

次のコマンドでブラウザーインターフェースを起動します。

python cli.py -web

tokentabはhttp://localhost:4747を開き、上部に合計、下部に項目別の詳細を表示する月次明細書のような形式でデータを提示します。

ダッシュボードは結果をキャッシュせず、リクエストごとにディスクからログを読み込むため、別のデータベースを維持しなくても新しく記録されたセッションが表示されます。localhostのみにバインドされ、データをアップロードすることはありません。また、外部フォントサービスを使用しないため、ネットワークに接続されていない状態でもインターフェースを利用できます。

別のポートを選ぶには--portを使用します。ブラウザーを自動的に開かずにサーバーを起動するには、--no-openを追加します。

python cli.py -web --port 8080 --no-open

トークンとコストの計算を理解する

トークン数

トークン合計は、テキストから推定したものではなく、対応ツールのログから直接取得されます。tokentabは、キャッシュの報告方法の違いも考慮します。Claudeはキャッシュの読み取りと書き込みを個別に記録しますが、Geminiはキャッシュ済みトークンを含む入力として報告します。tokentabは、同じトークンに二重に料金が発生しないよう、必要に応じてキャッシュ分を除外します。

モデルの料金

料金は、100万トークンあたりのドル単位としてtokentab/pricing/prices.pyにローカル保存されています。このツールは、ネットワーク経由で最新の料金を取得するのではなく、意図的に静的な料金表を使用します。

モデルの照合にはあいまい検索が使われるため、claude-opus-4-6-20260514のような日付付きモデル識別子は、より一般的なclaude-opus-4-6のエントリに一致します。モデルの料金が$0.00と表示された場合、その名前が料金表に一致しなかった可能性があります。CLIは、モデルが無料だと黙って判断するのではなく、この状態を報告します。

料金は可能な範囲での対応です。ベンダーが料金を変更した場合や、まだ認識されていないモデル名を追加した場合は、ローカルの料金表を更新してください。

アクティビティカテゴリ

coding、debugging、refactoring、testing、chat、exploringなどのアクティビティラベルは、使用されたツールとセッション最初のメッセージの文面から推定されます。この分類は決定論的に行われ、別のAIモデルは呼び出しません。

アクティビティラベルは、確定的な判断ではなく、参考情報として扱ってください。ラベルは大まかなパターンを明らかにするのに役立ちますが、作業の全体的な文脈を知っているのはあなただけです。

レポートを読み解く

  • 約80%を下回るキャッシュヒット率が継続している: コンテキストが頻繁に変化しているか、キャッシュが有効になっていない可能性があります。数週間続くパターンに比べると、単発の異常なセッションは重要性が低くなります。
  • 高価なモデルが多数の小規模な呼び出しを占めている: 大規模モデルが、頻繁に発生する限定的なタスクを処理している可能性があります。tokentabはこのパターンを示すため、その利用が意図したものかどうかを調査できます。
  • chatまたはexploringカテゴリが多い: 記録されたアクティビティの多くが、編集ではなく議論や読解に費やされていました。これは適切な場合もありますが、セッションが脱線していたことを示す場合もあります。

これらのパターンは調査の出発点であり、結論ではありません。該当するセッション中に実際に何をしていたかとレポートを照らし合わせてください。

高度なヒント: 別のプロバイダーを追加する

各プロバイダーはtokentab/providers/配下のモジュールとして実装されています。プロバイダーは、UsageRecordオブジェクトのフラットなリストを返すcollect()関数を公開します。共通レコード構造はtokentab/types.pyで定義されています。

  1. tokentab/providers/にプロバイダーモジュールを作成します。
  2. プロバイダーのローカルセッションファイルを読み込み、解析します。
  3. 関連する各利用エントリを共通のUsageRecord形式に変換します。
  4. collect()からレコードを返します。
  5. プロバイダーをtokentab/providers/__init__.pyに追加します。

レコードが共通形式になれば、既存の料金計算、グループ化、CLI出力、ダッシュボードで処理できます。READMEでは、最も簡単なテンプレートとしてClaudeパーサーを使い、追加の例については他の動作するパーサーを参照することを推奨しています。

実用的な利用のヒント

  • 最近の変化を把握するため、デフォルトの7日間レポートを定期的に実行します。
  • より広範な支出パターンを確認するときは、月間ビューを使用します。
  • 特定のコードベースを調査する前に、プロジェクトで絞り込みます。
  • tokentabのデータを使ったスクリプトやカスタムレポートを作成するときは、JSONをエクスポートします。
  • モデルの料金が$0.00と報告された場合は、料金表を確認します。
  • 視覚的な確認にはダッシュボードを、自動化や共有にはCLIを使用します。

まとめ

tokentabは、認証情報を必要とせず、データをコンピューターの外部に送信することもなく、ローカルのClaude Code、Codex、Gemini CLIのログを実用的なトークン・コストレポートに変換します。まずはデフォルトの7日間CLIビューから始め、期間、プロバイダー、プロジェクトのフィルターで結果を絞り込み、別の形式で表示したいときはJSONまたはlocalhostのダッシュボードを使用してください。このプロジェクトはMITライセンスで提供されています。