claudestat — Claude Code & OpenCode usage tracker with MCP

---

目次

• claudestat を選ぶ理由
• ClaudeStat はどんな人向けですか？
• 次のような場合は ClaudeStat をお使いください
• Claude に自身について尋ねる
• 機能
• クイックスタート
• 要件
• インストール
• コマンド
• ダッシュボード
• ライブラリ API
• OpenCode のサポート
• MCP サーバー
• MCP バンドル（スタンドアロン）
• 設定
• トラブルシューティング
• FAQ
• アンインストール
• コントリビューション
• ライセンス

---

claudestat が選ばれる理由

コーディングエージェントの分野には、異なる 2 つの用途があります。

• 何が起きたか — コスト、トークンの合計、日次／週次／月次レポートです。ccusage は過去の分析における代表的なツールです。
• 今、何が動いているか — クォータを使い切る前に、ライブセッションや現在の予算を確認します。claudestat と OpenUsage はこの用途に対応しています。

claudestat は Claude Code のイベント発生時にフックを実行し、すべてのデータをローカルの SQLite に保存して、ライブ Web ダッシュボード、クォータアラート、MCP サーバーを提供します。

	claudestat	ccusage	OpenUsage	Langfuse	Agent Trail
リアルタイムのイベントストリーム	✅	一部対応	✅	✅	✅
ライブのターミナルトレース（watch）	✅	—	—	—	—
Web ダッシュボード	✅	—	TUI	✅	✅
クォータアラート＋キルスイッチ	✅	—	クォータのみ	—	—
ループ／過剰実行の検出	✅	—	—	—	—
MCP サーバー（Claude に自身について質問）	✅	—	—	—	—
Claude Code 対応	✅	✅	✅	✅	✅
OpenCode 対応	✅	✅	✅	—	—
ツールのトレース	✅	制限あり	—	✅	✅
エージェント／サブエージェント	✅	—	—	✅	✅
オーケストレーションビュー	✅	—	—	✅	✅
過去のレポート	✅	✅	一部対応	✅	✅
ローカル優先／SQLite（クラウド不要）	✅	✅	✅	設定可能	✅

大きな違いは確認するタイミングです。ccusage は昨日いくら使ったかに答え、claudestat はコーディング中に何が起きているかを表示します。Langfuse と Agent Trail は可観測性を提供しますが、クラウド優先であるか、インフラのセットアップが必要です。

claudestat が役に立ったら、⭐ を付けてください。他の開発者が見つけやすくなります。

---

ClaudeStat はどんな人に向いていますか？

ClaudeStat は、AI コーディングエージェントを使用していて、エージェントが何をしているのか、どれくらいのコストがかかるのか、いつ非効率になるのかを把握したい開発者向けです。

特に、次のような場合に便利です。

• Claude Code を使用している
• OpenCode を使用している
• 複数のコーディングエージェントを同時に実行している
• サブエージェントとオーケストレーションを使用している
• MCP サーバーを使用している
• トークンと API のコストを把握したい
• 長時間実行するエージェントセッションを扱っている
• ローカル／プライベートなテレメトリーを求めている（クラウド不要）
• セッション後のレポートではなく、リアルタイムの可視性が必要

---

次のように使う場合は ClaudeStat をお試しください...

次のことをしたい場合は、ClaudeStat をお使いください。

• Claude Code をリアルタイムで監視する
• OpenCode をリアルタイムで監視する
• トークンの使用量と AI コーディングのコストを追跡する
• 最も多くの予算を消費するツールを確認する
• エージェントとサブエージェントを監視する
• MCP のアクティビティを調べる
• コンテキストの過剰消費やループを検出する
• アラートとキルスイッチでクォータを保護する
• マルチエージェントのオーケストレーションを把握する
• テレメトリーを完全にローカルに保つ

---

Claude に自身について質問する

claudestat には MCP サーバーが付属しています。登録すれば、ターミナルから離れずに Claude Code 自身の使用状況について質問できます。

claude mcp add claudestat -s user -- claudestat-mcp

あとは質問するだけです。

> How much did I spend this week?
> What are my top 5 tools by cost?
> Break down my usage by model
> What's my cost projection for next month?

MCP の全リファレンス →

---

機能

• ツール呼び出しのライブ追跡 — 実行中のすべての呼び出しについて、所要時間とトークンコストを表示します
• OpenCode 対応 — OpenCode セッションでも同じライブダッシュボードを利用できます（ツール呼び出し、プロンプト、モデル、インテント）
• クォータガード — 70％、85％、95％でアラートを表示します。オプションのキルスイッチを使うと、使用率が X％に達した時点で新しいセッションをブロックできます
• ループ検出 — コンテキストの浪費を検出し、推定損失コストを表示します
• 上位ツール — 予算を最も消費しているツールを確認できます。「その他」の行を展開すると、上位10件以外のツールも表示されます
• コスト予測 — トレンド、信頼区間、R² を含む線形回帰を行います
• 課金ブロック — 5時間の課金ウィンドウと、ブロックごとの累計支出を追跡します（claudestat blocks）
• セッション共有 — 任意のセッション概要を、書式設定済みの ASCII または JSON としてエクスポートします（claudestat share）
• 52週間のアクティビティヒートマップ — Analytics で年間を通じたコーディングアクティビティを可視化します
• 期間比較の差分 — Analytics の KPI に、前の期間と比べた傾向を ↑↓％ で表示します
• プロジェクトの検索とフィルター — プロジェクトをすばやく検索し、アクティビティ、コスト、効率のしきい値で絞り込めます
• オーケストレーションコマンドセンター — CC+OC のマルチエージェント実行をライブのスイムレーンビューで表示します。サイクルごとのコスト、トークン（キャッシュを含む）、変更ファイル、Git コミット、モデルの内訳を確認できます。サイクルのトレースはログローテーション後も保持されます
• Web ダッシュボード — 7つのタブ：Live、History、Projects、Analytics、Top、System、Orchestrate
• MCP サーバー — Claude が自身の使用状況に関する質問に答えられる9つのツールを提供します。スタンドアロンバンドルも利用できます（@statforge/claudestat-mcp-bundle）
• 週次インサイト — パターンを分析し、実行可能なヒントを提示します
• 複数ソース対応 — Claude Code と OpenCode のセッションをワンクリックで切り替えられます
• ソースフィルター — すべてのタブで、Claude Code / OpenCode による KPI、グラフ、ツールランキングを絞り込めます
• 複数ツールの連携 — 実際の競合検出機能を備えたライブインテントパネルを提供します（CC と OC が同じファイルを編集）
• プログラム向けライブラリ API — 独自のツールから dbOps、料金設定、インテリジェンス関数を直接インポートできます（v1.13.0+、@experimental）
• KPI ミニチャート — KPI カードに、コスト／ブロックの推移を示すインタラクティブな棒グラフと、コンテキストの推移を示す面グラフを表示します
• ヘッダーレイアウトの強化 — モデル名、プロジェクト、統一された高さのバッジを備えたコンパクトなナビゲーションバーです

---

クイックスタート

npm install -g @statforge/claudestat && claudestat setup
open http://localhost:7337

Claude Code のセッションを開始し、イベントが流れる様子を確認してください。これだけです。

---

要件

• Node.js >= 22（node:sqlite に必要です）
• Claude Code がインストールされていること（npm install -g @anthropic-ai/claude-code）

---

インストール

npm install -g @statforge/claudestat && claudestat setup

claudestat setup は Claude Code のフックをインストールし、デーモンをシステムサービスとして登録します。sudo は不要です。ログインするたびにデーモンが自動的に起動します（macOS では launchd、Linux では systemd、Windows ではタスクスケジューラ）。

NVM を使用していますか？ デフォルトの Node バージョンを使用していることを確認してください。

nvm use default && npm install -g @statforge/claudestat && claudestat setup

セットアップ後、フックを有効にするため Claude Code を再起動してください。

手動セットアップ

npm install -g @statforge/claudestat
claudestat install   # installs hooks into Claude Code
claudestat start     # start the daemon manually

---

コマンド

コマンド	説明
claudestat setup	1つのコマンドでセットアップします。フックをインストールし、デーモンをシステムサービスとして登録します
claudestat setup --uninstall	フックとシステムサービスを削除します
claudestat start / stop / restart	バックグラウンドデーモンを管理します
claudestat install / uninstall	Claude Code のフックをインストールまたは削除します
claudestat watch	ターミナルでライブトレースを表示します
claudestat status	クォータ、コスト、消費速度を表示します
claudestat top	コスト、呼び出し回数、または実行時間でツールを順位付けします
claudestat weekly	週間使用状況の概要を表示します
claudestat insights	使用状況を詳しく分析します。コスト、キャッシュ、効率、モデルが対象です
claudestat project	線形回帰によるコスト予測を表示します
claudestat config	設定を表示または編集します
claudestat doctor	インストールの状態を確認し、問題を診断します
claudestat blocks	5時間の課金ブロック履歴を表示します
claudestat share [session-id]	セッションの概要を ASCII または JSON でエクスポートします（クリップボードにコピーするには --copy を使用します）
claudestat export [format]	セッションデータを JSON または CSV にエクスポートします
claudestat roast	皮肉を交えた使用状況分析を表示します
claudestat resume	一時停止中のセッションを再開します
claudestat loops	ループ（コンテキストの過剰な切り替え）が検出されたセッションを一覧表示します
claudestat logs	デーモンのログを表示します（-n、--follow、--level を使用します）
claudestat update	更新を確認し、最新バージョンを npm からインストールします
claudestat version	バージョンを表示し、更新を確認します

コマンドの完全なリファレンスと出力例 →

---

ダッシュボード

ダッシュボードは http://localhost:7337 にあり、Live、History、Projects、Analytics、Top、System、Orchestrate の7つのタブがあります。

ダッシュボードの詳細 →

---

AI 開発ベンチマーク

claudestat は、AI をペアプログラミングのパートナーとして活用する人間の開発者によって開発されました。AI によって実装が加速されましたが、アーキテクチャ、設計、エンジニアリングに関する判断は人間が行いました。ふさわしいことに、claudestat は自身を計測しています。以下のすべての指標は、独自のイベントデータベースに基づいています。

協働の進め方

人間が担当	AI が実装し、常に人間がレビュー
プロダクトのビジョンと機能設計	TypeScript サービスの生成
MCP サーバーのプロトコルと設計	ツールのひな形、ダッシュボードのコンポーネント
データモデル（SQLite スキーマ）	リファクタリング、テストのひな形
アーキテクチャの判断	設定の解析、CLI コマンド
コードレビューと最終承認	ドキュメント、補助スクリプト

ワークフロー： Idea → Spec → AI implementation → Human review → Test → Refine → Merge

開発は反復的に進められ、単一のプロンプトで完了することはありませんでした。要件 → コンテキストの準備 → 生成 → レビュー → 修正 → 検証 → 繰り返し、という手順です。コードとテストは一緒に出荷され、人間によるレビューなしにマージされたものはありません。PR は予算内に収め、必要に応じて /chained-pr で分割しました。

AI 開発の原則

• AI がプロダクトに関する判断を下すことはありませんでした。
• すべての実装は、書面による仕様から開始しました。
• ドキュメントは、AI が実行可能なコンテキストとして扱いました。
• 生成されたコードはすべて、人間によるレビューが必須でした。
• 実装速度よりも、アーキテクチャの維持を優先しました。
• タスクの種類に応じてモデルを選択しました（複雑な機能には Claude Code、高速な反復には OpenCode）。

参考指標

指標	値
AI セッション	116件を記録
計測された開発時間	約344時間
セッションの平均効率	77/100
主なモデル	Claude Sonnet 4.6（CC セッション48件）
副次モデル	OpenCode：DeepSeek V4 Flash/Pro、GLM-5、Mimo v2.5（セッション68件）

ClaudeStat で計測。このプロジェクト独自のトラッキングツールです。値は概算です。

---

OpenCode のサポート

OpenCode を Claude Code と併用すると、claudestat は両方のセッションを自動的に検出し、「Live」タブにソース切り替え機能を表示します。

Claude Code と OpenCode を切り替えると、ダッシュボードを離れることなく、各セッションのリアルタイム表示（ツール呼び出し、プロンプト、モデル名、インテントバッジ、タイミング）を確認できます。

機能	Claude Code	OpenCode
ツール呼び出し（Read、Write、Bash、Edit…）	✅	✅
ブロックごとのプロンプト	✅	✅
モデル名	✅	✅
インテントの検出（探索中／実装中…）	✅	✅
セッションのコスト	✅	✅
週間使用状況チャート	✅	✅
ブロックごとのコスト内訳	✅	✅
クォータ／コンテキストウィンドウ	✅	—

OpenCode のデータは、設定不要でローカルの SQLite データベースから直接読み取られます。

---

MCP サーバー

claudestat には使用状況を照会するための9つのツールを備えた MCP サーバーが含まれています。一度登録するだけです。

claude mcp add claudestat -s user -- claudestat-mcp

その後、Claude に 「クォータの状況は？」、「最新のセッションを表示して」、「コスト上位5つのツールは？」、「コンテキストウィンドウの状態は？」、「今日の概要は？」 などと尋ねられます。

このサーバーは、コンテキストの飽和（50／75／90％）、週間クォータのしきい値、5時間の請求サイクル上限についても プッシュ通知 を送信するため、こちらから尋ねなくても Claude が事前に警告します。

v1.16.0 以降、MCP サーバーは独自実装の JSON-RPC エンジンではなく、公式の @modelcontextprotocol/sdk（v1.30.0）で動作します。これにより、標準に準拠したハンドシェイク、最新の MCP クライアントとのプロトコルバージョンのネゴシエーション、stdin の EOF 時の信頼性の高い起動／終了、ツール引数の適切な入力検証が可能になります。公開 API に変更はないため、既存の登録はそのまま引き続き動作します。

ツール	説明
get_quota_status	5時間サイクルの割合、モデルごとの週間利用時間、消費率、プランの検出
get_current_session	最新セッションのコスト、トークン数、効率、ループ
get_session_stats	過去 N 日間の集計統計
get_top_tools	コスト、回数、または所要時間に基づくツール上位10件
get_usage_insights	プロジェクトごとのコスト、キャッシュによる節約、出力／入力比率、ピーク時間
get_model_breakdown	Claude モデルごとのコストとセッションの内訳
get_weekly_insight	実行可能なヒントを含む週間概要
get_context_status	飽和度バー付きの現在のコンテキストウィンドウ使用状況
get_daily_summary	今日と昨日、および過去7日間の平均の比較

MCP ツールのリファレンス →

MCP バンドル（単体版）

依存関係を軽くしたい場合は、MCP サーバーを単体パッケージとしてインストールできます。CLI もデーモンもなく、stdio MCP サーバーとその SQLite リーダーだけが含まれます。

npm install -g @statforge/claudestat-mcp-bundle
claude mcp add claudestat -s user -- npx @statforge/claudestat-mcp-bundle

同じ9つのツール、同じコンテキスト通知を、追加のフットプリントなしで利用できます。

バンドルのリポジトリ →

---

ライブラリ API

@experimental（v1.13.0+） — プログラムから使用する API は、v2.0.0 まではマイナー／パッチリリースで変更される可能性があります。組み込む場合は、バージョンを正確に固定してください。

claudestat には CLI と併せて TypeScript ライブラリエントリーポイントが用意されています。spawn や出力の解析を使わず、セッションデータを直接読み取るエクスポーター、アラート機能、インテグレーションを構築できます。

import { dbOps, analyzeSession, computeProjection, configure } from '@statforge/claudestat'

// Opt out of the daemon-required guard (CI / batch jobs):
configure({ throwOnNoDaemon: false })

const sessions = dbOps.getAllSessions(20)
const report   = analyzeSession(events, costUsd)
const forecast = computeProjection(30)

デフォルトでは、最初の dbOps.* 呼び出し時に http://127.0.0.1:7337/health を確認し、デーモンが停止している場合は DaemonNotRunningError をスローします。純粋関数（findPricing、analyzeSession、computeProjection、…）は確認を行いません。

項目	安定性
dbOps（50個以上の読み取り専用クエリ関数）	@experimental — 遅延デーモンガード付き
価格テーブル（MODEL_PRICING、KNOWN_CONTEXT_WINDOWS、PRICING）	@experimental
インテリジェンス（analyzeSession、detectLoops、predictSaturation、…）	@experimental
予測＋クォータ（computeProjection、computeQuota、…）	@experimental
configure({throwOnNoDaemon})	@experimental

ライブラリの完全なリファレンスと3つの実例 →

---

設定

設定は ~/.claudestat/config.json に保存されています。claudestat config で表示するか、ファイルを直接編集してください。

claudestat config --kill-switch true --threshold 90
claudestat config --plan max5
claudestat config --alerts false

設定の完全なリファレンス →

---

仕組み

Claude Code / OpenCode event
      │
      ▼
  Hook script  (~/.claudestat/hooks/event.js)
       │  POST JSON → daemon
       ▼
  Daemon  (localhost:7337)
       │  stores events in SQLite
       │  enriches with JSONL token data
       │  runs pattern analyzer
       │  context/quota push notifications
       ▼
  ┌──────────────────────────────────┐
  │  Dashboard (React + Vite)        │
  │  Terminal (claudestat watch)     │
  │  MCP Server (9 tools)            │
  │  Library API (dbOps, pricing)    │
  └──────────────────────────────────┘
              │
              ▼
  You see everything — live

---

トラブルシューティング

claudestat start が約5秒間ハングする 正常です。初回の require('express') の読み込みには数秒かかります。デーモンは実行中です。「Daemon started」の確認メッセージが表示されるまでお待ちください。

フックが実行されない／ダッシュボードにイベントが表示されない claudestat doctor を実行してください。すべてのコンポーネントを確認し、修正に必要な正確なコマンドを表示します。

インストール後に claudestat コマンドが見つからない NVM を使用している場合、バイナリが誤った Node バージョンを参照している可能性があります。

nvm use default && npm install -g @statforge/claudestat && hash -r claudestat

キルスイッチが新しいセッションをブロックしている claudestat config --kill-switch false で無効にするか、5時間のクォータ期間がリセットされるまでお待ちください。

レート制限に近づいている デーモンは60秒ごとにクォータを確認し、70％、85％、95％で警告を記録します。claudestat status でいつでも確認できます。

複数のプロジェクトを扱う claudestat はすべてのプロジェクトを自動的に追跡します。「Projects」タブでは、作業ディレクトリごとにセッションがグループ化されます。

すべてのセッションのコストがダッシュボードで0／$0.00と表示される トークンデータはフックイベントではなく、Claude Code の JSONL ファイルから取得されます。Claude Code が JSONL ログを書き込んでいることを確認してください。~/.claude/projects/ に .jsonl ファイルがあるか確認します。ディレクトリが空の場合、Claude Code でログ記録が有効になっていない可能性があります。

ターミナルを閉じるとデーモンが停止する デーモンをシェルセッション終了後も実行し続けるには、nohup を使って起動する必要があります。

nohup claudestat start &

または、claudestat setup を使うとシステムサービスがインストールされます（macOS では launchd、Linux では systemd、Windows ではスケジュールされたタスク）。

claudestat export の出力が空になる セッションが表示されない場合、Claude Code のセッション中にデーモンが実行されていなかった可能性があります。claudestat status を確認し、claudestat start で再起動してください。過去のデータのみを対象とする場合（実行中のデーモンがない場合）でも、エクスポートではローカルの SQLite データベースが読み取られます。そのため、デーモンの実行中に記録された過去のセッションはいつでも利用できます。

ループ検出が頻繁すぎる／不十分 しきい値と期間を調整してください。

claudestat config --loop-threshold 5   # default: 8 calls
claudestat config --loop-window 90     # default: 120 seconds

MCP サーバーが応答しない デーモンを再起動（claudestat restart）し、登録されていることを確認してください。

claude mcp list

一覧にない場合は、再度実行してください：claude mcp add claudestat -s user -- claudestat-mcp

OpenCode のセッションが表示されない claudestat は ~/.local/share/opencode/opencode.db から OpenCode のデータを読み取ります。このファイルが存在しない場合、OpenCode がまだ実行されていないか、お使いのシステムで別のデータパスが使用されています。初期化するために、少なくとも一度 opencode を実行してください。

起動時に Node.js の実験的な SQLite 警告が表示される 想定される動作です。Node 22 では node:sqlite は実験的機能です。この警告は自動的に抑制されます。繰り返し表示される場合は、Node.js 22 以降を実行していることを確認してください（node --version）。

FAQ

claudestat とは何ですか？ccusage とは何が違いますか？ claudestat は Claude Code 用のリアルタイムモニターであり、ログリーダーではありません。各ツール呼び出しの実行時にフックし、トークン使用量とコストをリアルタイムで追跡し、設定可能なアラートでクォータを保護するとともに、MCP サーバーを公開します。ccusage はセッション終了後に JSONL の履歴を読み込みますが、claudestat はコーディング中に動作します。

Claude Code のコストを追跡するにはどうすればよいですか？ npm install -g @statforge/claudestat && claudestat setup でインストールし、http://localhost:7337 を開いてライブダッシュボードを表示します。概要をすばやく確認するには claudestat status を、データをすべてエクスポートするには claudestat export を使用します。

claudestat は Claude Pro、Max 5、Max 20 で動作しますか？ はい。claudestat はプランを自動検出します。claudestat config --plan max5 を使って手動で指定することもできます。

データはサーバーに送信されますか？ いいえ。すべてのデータは ~/.claudestat/ の SQLite にローカル保存されます。クラウドへの依存は一切ありません。

claudestat は Windows で動作しますか？ はい。macOS、Linux、Windows のすべてに対応しています。Windows では、claudestat setup が自動起動用の Scheduled Task を登録し、クリップボードには clip を使用し、デーモンのヘルスチェックには Node 組み込みの HTTP クライアントを使用します。

MCP バンドルとは何ですか？ @statforge/claudestat-mcp-bundle は、MCP サーバーのみを含むスタンドアロンの npm パッケージです。CLI、ダッシュボード、デーモンは含まれません。claudestat デーモン全体を実行せずに、MCP 経由で Claude に独自の統計情報を照会させたい場合にインストールしてください。

claudestat をプログラムから使用できますか？ はい。@statforge/claudestat から dbOps、computeProjection、analyzeSession、createMcpServer などの関数を直接インポートできます。詳しくは［ライブラリ API］(#library-api) のセクションをご覧ください。

---

アンインストール

claudestat setup --uninstall                          # remove hooks + system service
rm -rf ~/.claudestat                                  # macOS / Linux
Remove-Item -Recurse -Force "$env:USERPROFILE\.claudestat"  # Windows (PowerShell)

手動でインストールした場合は、claudestat uninstall を使うとフックのみを削除できます。 Windows では、claudestat setup --uninstall を実行すると Scheduled Task も削除されます。

---

コントリビューション

PR を歓迎します！ガイドラインの全文は CONTRIBUTING.md をご覧ください。

git clone https://github.com/DeibyGS/claudestat
cd claudestat
npm install
node --require tsx/cjs tests/index.ts   # run all tests

最初に取り組むのに適した分野：パターンアナライザー（src/pattern-analyzer.ts）、ダッシュボードのコンポーネント（dashboard/src/components/）、新しいコマンド。

---

ライセンス

MIT — ご自由にお使いください。フォークして、公開できます。