stormzhang/token-tracker

Claude Code & Codex 本地 token 追踪 — 状态栏（Codex 业界首创伪 statusline）、GitHub 风格热力图、多模型成本分析。 | Local token tracker for Claude Code & Codex — status line (industry-first Codex faux statusline), GitHub-style heatmap, multi-model cost analysis

Token Tracker（tt）

機能概要 – Token Tracker は、Claude Code、Codex、Kimi Code の3つの人気コードアシスタントエージェントを使用する際に消費するAIモデルトークンの量を監視するローカルなコマンドラインユーティリティです。エージェントのローカルトランスクリプトファイルを読み取り、トークン数を集計し、金銭的コストを推定し、情報をいくつかの便利な場所に表示します：

エージェント自身のターミナルUI内に表示されるカスタム StatusLine、
スプリットウィンドウ（iTerm2、Ghostty、tmux）に固定できるライブ「サイドバー」ペイン、
tt daily、tt weekly などで呼び出せる日次/週次/月次レポートのセット。

すべてのデータはマシン上に残ります。ネットワークへのアップロードはありません。

主な機能（READMEより）

機能	仕組み
3つのエージェントの統合追跡	Claude Code JSONLログ、Codex JSONL + SQLite、Kimi Code wire JSONLを読み取ります。トークンはセッションごと、モデルごとに合計されます。
StatusLine統合	• Claude Code – 公式のStatusLine API（4行レイアウト）を使用。 • Codex – Stop フックを介して2行のプレーンテキストを注入（新しいバージョンでは色なし）。 • Kimi Code – 公式の `status_line` インターフェース（単色のライン）を使用。
ライブサイドバー（`tt sidebar`）	5秒ごとに更新される狭いペインで、アクティブなセッション（過去5時間）、3都市の時計、最近のプロンプト、ステータスライト、最後のAI応答から抽出された「次のステップ」の提案を一覧表示します。行をクリックすると、対応するiTerm2/tmuxペインにジャンプします。
現在のセッションの自動スプリットスクリーン	CodexまたはKimi Codeセッション内で `$tt-sidebar` と入力すると、ツールは右側に1/3幅のペインを開き、そのセッションの完全なプロンプト履歴を表示します。
クォータ監視	一般的な5時間および7日間の制限に対するスライディングウィンドウの使用量を、プログレスバーとリセットまでのカウントダウンとともに表示します。
コスト分析	LiteLLMの価格データと、主要モデル（Claude Opus、Sonnet、Gemini、Grok、Kimi、GLM、Qwenなどの中国モデル）をカバーする組み込みのフォールバックテーブルを使用します。セッションごと、日次、週次、月次のコストを計算します。
テーマ対応の出力	6つのカラーテーマ（Catppuccinファミリー、Nord、Dracula）。テーマはCLIレポートとエージェントのステータスラインの両方に適用されます。
ゼロコンフィグ検出	初回実行時に、インストールされているエージェントを自動検出し、ローカルデータディレクトリを読み取ります。
プライバシーファースト	データはどこにも送信されません。すべて `~/.config/token-tracker` にローカルに保存されます。

典型的なワークフロー

インストール – ワンライナー curl … | bash を実行します。スクリプトは最適なインストーラー（uv、pipx、またはプライベートvenv）を選択します。
セットアップ – tt setup は短いインタラクティブウィザード（言語、テーマ、各エージェントのステータスラインを引き継ぐかどうか）を案内します。
使用 –
- tt または tt daily は、過去1年間のトークン使用量のGitHubスタイルのヒートマップを表示します。
- tt status は今日の合計とクォータのパーセンテージを表示します。
- tt weekly / tt monthly は棒グラフのレポートを生成します。
- tt sidebar はライブペインを開きます。tt sidebar --once は単一のスナップショットを出力します。
- Codex/Kimiセッション内で $tt-sidebar と入力すると、自動スプリットスクリーンビューが表示されます。
調整 – tt theme set <name> でテーマを変更するか、tt setup を再実行してステータスライン設定を変更します。
アンインストール – tt unsetup はフック/スキルを削除し、以前のカスタムステータスラインを復元します。

誰にとって役立つか？

AIコーディングアシスタントを頻繁に使用する開発者 – トークン消費を監視して、予期しない請求を避ける必要がある人。
クォータを共有するチーム（例：5時間のスライディングウィンドウ） – 制限にどれだけ近いかをすばやく視覚的に確認したい人。
整理されたターミナルUIが好きな人 – サイドバーとステータスラインは、別のダッシュボードを開かずに一目でわかるメトリクスを提供します。

制限事項/考慮事項

サポートされている3つのエージェントでのみ動作します。他のLLMフロントエンドは無視されます。
すべてのコスト計算は静的価格テーブルに依存しています。プロバイダーが価格を変更した場合、組み込みデータを更新する必要があります。
「次のステップ」の提案はルールベースであり、モデルによって生成されるものではありません。
Windowsでは、サイドバーはコンソールのGBKエンコーディングに適応しますが、一部の色の忠実度が低下する場合があります。

クイックリファレンス（コマンド）

tt setup          # 初期設定、ステータスラインフックとサイドバースキルのインストール
tt               # `tt daily` と同じ – 年間ヒートマップ
tt daily          # トークン使用量のヒートマップ
tt status         # 今日の合計 + クォータバー
tt weekly         # 週次レポート（コスト、トークン、トレンド）
tt monthly        # 月次レポート
tt sessions       # 最近のセッションを一覧表示、並べ替え可能
tt sidebar        # アクティブなセッションを含むライブペイン
tt sidebar --once# 単一スナップショット
tt theme …       # テーマの表示/一覧表示/プレビュー/設定
tt unsetup        # 注入されたすべてのフック/スキルを削除

結論 – Token Tracker は、開発者がAIコーディングエージェントが消費しているトークン数、そのコスト、およびクォータ制限に近づいているかどうかを、ターミナルからすべて具体的に可視化できる、本格的なオープンソースのPythonツールです。