Codex Usage Tracker: ローカル Codex 利用量を追跡できる台帳に変える

ここ最近のローカル AI coding tool には、かなり現実的なのに、まだ真面目に扱われていない問題があります。

Codex を使っていても、実際にどこで配分が削られているのかは意外と見えていない。

token や credits が急に減る原因は、いつも目立つ大きな 1 回の作業とは限りません。むしろ、次のような小さな要因が積み重なることが多いです。

ある thread の context が膨らみ過ぎている;
ある model の cache reuse が悪い;
auto-review や subagent、長時間の chat が裏でじわじわ使っている;
「最近かなり使った」は分かっても、どの会話や project が高くついたのか説明できない。

今日取り上げたい douglasmonsky/codex-usage-tracker は、まさにこの可観測性の穴を埋めるための project です。

GitHub repository page、release page、README を 2026-06-30 時点で確認すると、この repository は 133 stars、8 forks、作成日は 2026-05-17、直近の公開更新は 2026-06-30 です。主言語は Python、license は MIT。最新 release は v0.12.0 で、公開日は 2026-06-29 です。

Project overview

項目	内容
Repository	douglasmonsky/codex-usage-tracker
位置づけ	ローカル Codex 利用データ向けの dashboard、CLI、MCP tools、companion skill
Stars	133
Forks	8
主言語	Python
作成日	2026-05-17
直近の公開更新	2026-06-30
Latest version	v0.12.0
Release date	2026-06-29
License	MIT
実行形態	ローカル SQLite + localhost dashboard + CLI + MCP

これは「もう 1 つの agent」ではなく、Codex に会計の見える化を足す tool です

README はかなり率直です。この project は local-first dashboard、Codex plugin、companion skill として、Codex の token と usage credits がどこへ流れているのかを理解するために作られています。

仕組みはシンプルですが、とても実務的です。

手元のマシンに既に出力されている Codex の JSONL ログを読む;
集計済みカウンタをローカル SQLite に索引する;
dashboard、CLI、MCP tools、companion skill を提供する;
「どの thread が高いのか」「どの model が重いのか」「どの subagent が継続的に消費しているのか」を追跡できるようにする。

価値があるのは、agent を賢くすることではなく、AI 利用の実態を後から監査できることです。

この project が扱っているのは、AI coding の“運用目線”です

サーバー、DB、CI、API gateway には、私たちは当然のように observability を求めます。

でもローカル AI coding tool になると、まだ「動けばよい」で止まっていることが多い。その結果、

毎日 agent と協働している;
局所的な会話は見えている;
でも 1 週間の消費構造は説明できない;

という状態に陥りがちです。

README が挙げている消費要因もかなり現実的です。

long-running chats;
low cache reuse;
reasoning spikes;
spawned subagents;
auto-review passes。

つまりこの tool が見ているのは、単発リクエストの値段ではなく、ローカル AI workflow 全体のコスト地形です。

4 つの dashboard 視点があるから、単なる総量表示で終わらない

この project の良いところは、合計値を出して終わらないことです。

README では、次の dashboard view が紹介されています。

Insights
Calls
Threads
Diagnostics

この分け方はかなりうまいです。

Calls では個別の消費を追い、正確な token accounting や cache 差分、実行時 evidence を見られます。Threads では長い会話、subagent、auto-review を 1 つの作業単位として捉えやすい。Insights は高コスト thread、低 cache reuse、context bloating、pricing gap のような問題を先に浮かび上がらせます。Diagnostics はさらに commands、Git interactions、file reads、file modifications、usage-drain reports まで横断的に見せます。

だからこの tool は「昨日いくら使ったか」だけではなく、

どの thread が高かったのか;
どの段階で重くなったのか;
cache 効率が崩れているのか;
どんな使い方が継続的にコストを上げているのか;

まで掘り下げられます。

ローカル CLI、MCP、companion skill があるので、見て終わりにならない

この project でもう 1 つ気に入ったのは、dashboard だけに閉じていない点です。

README にある代表的な command は次の通りです。

codex-usage-tracker summary --preset last-7-days
codex-usage-tracker query --since 2026-06-01 --min-credits 1
codex-usage-tracker session <session-id>
codex-usage-tracker export --output usage.csv
codex-usage-tracker open-dashboard

さらに install 後には、

ローカル dashboard;
Codex plugin;
MCP tools;
companion skill;

が揃います。

この構成は重要です。こういう tool を本当に使い込む人は、単に「たまにブラウザで眺めたい」のではなく、

定期的な usage review に組み込みたい;
Codex 自身に今週の異常消費を説明させたい;
集計データを別スクリプトへ渡したい;

と考えることが多いからです。

その意味で、CLI と MCP は補助機能ではなく、日常 workflow に入るための本体の一部です。

Privacy 境界の扱いがかなり慎重です

ここは特に好感を持ちました。

README は、この project が aggregate metrics のみを保存し、次のような内容を SQLite、CSV、生成された dashboard HTML に書き込まないと明言しています。

prompts;
assistant messages;
tool output;
pasted secrets;
raw transcript snippets;
raw context。

実行時 context を見る場合でも、明示的な操作で単一の元 JSONL を読むだけで、一般的な secret pattern の redact とサイズ制限がかかります。

つまり作者の発想は、

ログを別の black box に複製しない;
観測能力を大量保持に依存させない;
まず集計だけで大半の分析を済ませる;

というものです。

ローカル AI 対話ログを扱う tool として、この節度はかなり大事です。

これは個人向けの“小さな AI FinOps”とも言えます

もう少し引いた目で見ると、この project は 個人開発者や小規模チーム向けのローカル AI FinOps に近い面白さがあります。

もちろん、enterprise 向けの請求統制システムではありませんし、全 AI coding product を横断する共通会計基盤でもありません。

それでも、今まで誰もちゃんと扱ってこなかった問いに答え始めています。

どの thread が割に合わないのか;
どの project context が暴走しやすいのか;
どんな使い方が cache 効率を落としているのか;
どの会話を archive、分割、再出発すべきなのか。

agent 協働を語るとき、私たちはつい prompt、model、IDE integration、automation 深度ばかり見がちです。Codex Usage Tracker が扱っているのは、もっと地味で、でも確実に必要になる領域です。

AI coding が日常コストになったあと、開発者はどうやって自分の使い方を監査するのか。

どんな人に向いているか

特に向いているのは、次のような人です。

Codex を高頻度に使い、ローカルに多数の thread とログが溜まる人;
credits、token、cache hit、context 膨張を気にし始めた人;
ローカル優先と privacy 境界を保ち、第三者へログを上げたくない人;
usage 分析を CLI、script、MCP workflow に入れたい人。

逆に、たまに 1、2 回 Codex を開くだけなら少し重く感じるかもしれません。この tool の価値は、継続利用のあとに生まれる可観測性にあります。

もちろん、境界もはっきりしています

README も明言している通り、これは unofficial project です。OpenAI の公式 product ではありません。

だから理解すべき立ち位置は次の通りです。

ローカル Codex ログを分析する独立した OSS;
公式 billing backend ではない;
すべての AI coding product を横断する標準会計基盤でもない。

ただ、その代わりに焦点は非常に鋭いです。まずは ローカル Codex 利用分析を本当に使える形にする。そこに集中しています。

まとめ

douglasmonsky/codex-usage-tracker が面白いのは、「agent 関連 repo がまた 1 つ増えた」からではありません。

この project が選んだ問題が、かなり現実的だからです。

もう Codex は日常的に使っている;
消費構造は既に複雑になっている;
でも、まだまともなローカル観測面がない。

この project は JSONL ログ、SQLite 集計、dashboard、CLI、MCP、companion skill を比較的節度ある形でつなぎ、その空白を埋めています。

多くの AI tool が「どうすれば agent にもっと仕事をさせられるか」を競っている一方で、Codex Usage Tracker が扱っているのは別の問いです。

agent が十分に日常化したあと、開発者は自分の利用コストをどう理解するのか。