Codex用のヘルスチェックCLI「codex-healthkit」を作った理由

Codexを毎日の作業で使うようになってから、気になる場所が少し変わった。
最初は、どのモデルがよいか、どんな指示を出すと作業しやすいかに目が向いていた。

でも、使う時間が増えると、それだけでは足りない。

ローカル環境は大丈夫なのか。
ログやsessionは増えすぎていないか。
何か問題が起きた時、どの情報なら人に見せてもいいのか。
逆に、絶対に出してはいけないものは何か。

そういうところが気になってくる。

以前、Codexを使い倒すなら、使用量だけでなくローカル環境も点検すべきって話を書いた。
その時は、codex doctor、sessions、SQLiteログサイズ、rolloutまわりを手で確認した記録だった。

今回はその続き。

毎回手で見るのは面倒なので、Codex用の小さなヘルスチェックCLIを作った。
名前は codex-healthkit。

大げさなツールではない。
むしろ逆。

中身を読まない。
勝手に掃除しない。
外へ送らない。
まずはローカルのmetadataだけを見る。

AIエージェントを日常運用するなら、プロンプトやモデルだけでなく、ローカル環境と共有境界も運用対象になる。
この記事は、そのために作った小さなCLIの記録です。

確認日は2026年7月6日。
codex-healthkit は v0.1.0-alpha.1 のprereleaseとして公開しています。

Codexを毎日使うと、モデル性能以外が気になってくる

Codexをたまに使うだけなら、気になるのは回答の質や速度です。
どのモデルがよいか。
どのpromptなら意図が伝わるか。
どこまで任せられるか。

それはもちろん大事。

ただ、自分の運用では、Codexは単発の相談相手ではなくなってきた。
ブログの下書き、WordPressの確認、GitHub repoの整理、AIチームのthread運用、公開後の同期。
かなりの作業がCodexの中を通る。

さらに、Mac miniをCodexの母艦にしたら、外出先でもAIチームの仕事が回るようになったでも書いたように、常時稼働MacをCodexの作業場として使い始めている。

そうなると、気になるのはAIとの会話だけではない。

ローカル環境そのものです。

codex doctor は通るのか。
sessionsはどのくらい増えているのか。
SQLiteのWALが急に大きくなっていないか。
相談やissue作成の前に、どこまでなら共有してよいのか。

ここを曖昧にしたまま使い続けるのは、少し怖い。
便利だからこそ、運用の外側も見ておきたい。

前回は手で見た。今回は小さなCLIにした

前回の記事では、ローカル環境を手で見た。

codex --version を確認する。
codex doctor --summary を見る。
sessionsやarchived sessionsのサイズを見る。
SQLiteログのファイルサイズを見る。

そのくらいでも、かなり見えるものはある。

ただ、毎回やるには面倒だった。
コマンドを忘れる。
見る場所が散らばる。
問題が起きた時に、何を貼ればよくて、何を貼ってはいけないのか迷う。

プロンプトに手順を毎回書くより、繰り返す作業は小さな形にしておきたい。
これは、以前にAIに任せる仕事は、プロンプトではなくskillにした方がいいで書いた感覚にも近い。

ここで必要だったのは、全部入りの監視ツールではなかった。

usage dashboardでもない。
自動cleanupでもない。
transcript parserでもない。

まずは、ローカルの状態を軽くまとめる小さなCLI。
しかも、共有しやすい形で。

そこで codex-healthkit を作った。

2026年7月6日時点では、source-only alphaです。
npm配布はまだしていない。
Product HuntやHacker Newsに出す段階でもない。

まずはGitHubに置き、cloneして試せるところまで。
そのくらいの温度感です。

codex-healthkitは、中身ではなくmetadataを見る

codex-healthkit の方針は、かなり絞っている。

見るのは、ローカルファイルのmetadata。
つまり、サイズ、件数、存在、状態のサマリー。

デフォルトでは外部の codex コマンドも実行しない。
Codex CLIの公式doctorを使うモードは用意しているけれど、それはoptionalです。

確認するものは、このあたり。

• codex commandが存在するか
• active sessions directoryのサイズと .jsonl 件数
• archived sessions directoryのサイズと .jsonl 件数
• quarantine directoryのサイズ
• logs_2.sqlite、logs_2.sqlite-shm、logs_2.sqlite-wal のファイルサイズ
• SQLite WALが大きくなりすぎていないかのsize-only summary
• optionalでCodex CLI version
• optionalで codex doctor --json のredacted summary

一方で、見ないものも明確にしている。

• credentials
• token files
• cookies
• localStorage
• OS credential stores
• SQLite contents
• session transcript contents
• account IDs
• email addresses
• raw codex doctor output
• browser profiles
• usage / quota
• cleanup / delete / archive

ここが一番大事だった。

ヘルスチェックと言うと、つい何でも見たくなる。
でも、AIエージェントの作業環境では、見ないことにも意味がある。

相談しやすいレポートを作るために、危ない情報まで読みに行ったら本末転倒です。

実際の出力はredacted exampleだけを使う

この記事では、実ローカルのreportは使わない。

使うのは、GitHub上に置いている examples/report.redacted.md です。

たとえば、こういう形。

# codex-healthkit report

Generated: 2026-07-05T00:00:00Z

## Summary

- status: `ok`
- sqlite_note: ok: no large WAL spike detected by size-only check.
- default_mode: local file metadata only

## Safety

- auth files read: `no`
- token files read: `no`
- cookies read: `no`
- SQLite contents read: `no`
- session transcript contents read: `no`
- healthkit telemetry/upload: `no`

見せたいのは、実際の自分の容量や件数ではない。
レポートの形と、安全境界です。

auth filesは読まない。
token filesは読まない。
cookiesは読まない。
SQLite contentsは読まない。
session transcript contentsは読まない。
telemetryやuploadもしない。

この一覧が、codex-healthkit の中心にある。

「安全です」と言い切りたいわけではない。
そうではなく、共有前に自分で確認しやすい、低リスクなreportを目指している。

GitHubに出す前に、最低限の公開品質を整えた

最初は自分用の小さなCLIだった。

ただ、GitHubに置くなら、最低限は整えておきたい。
READMEだけ置いて終わりにはしない。

今回、公開前に整えたのはこのあたりです。

• README.md
• README.ja.md
• LICENSE
• SECURITY.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SUPPORT.md
• CHANGELOG.md
• GitHub Actions
• issue templates
• pull request template
• dependabot
• usage guide
• FAQ
• safety boundary
• release checklist
• redacted example
• tests

さらに、public clone QA、macOS QA、Linux QA、release、tag、topics、description、homepage、README badgeも確認した。

2026年7月6日時点では、v0.1.0-alpha.1 をprereleaseとして公開している。

MIT License。
macOSとLinuxで検証済み。
WindowsはBash実装としてはまだ未対応。

OpenAI公式プロジェクトではありません。
自分のCodex運用から出てきた、個人の小さなOSSです。

これはusage dashboardでもcleanup toolでもない

ここは誤解されないように書いておきたい。

codex-healthkit は、Codexの使用量を管理するdashboardではない。
quotaを見るツールでもない。
sessionを削除するツールでもない。
transcriptを解析するツールでもない。

やらないことを、かなり多めに決めている。

• npm配布はまだしない
• cleanup toolにしない
• background monitoringにしない
• usage dashboardにしない
• account switcherにしない
• transcript parserにしない
• Product HuntやHacker Newsへ急がない

理由は単純です。

最初から便利にしすぎると、見る範囲が広がる。
見る範囲が広がると、読まなくていいものまで読みたくなる。

Codexのローカル環境を扱うなら、まず境界を狭くする。

今の自分には、その方が合っている。

小さく試すなら、cloneしてcheckだけでいい

試す場合は、GitHubからcloneする。

git clone https://github.com/Ishikawa-Hidekazu/codex-healthkit.git
cd codex-healthkit
./bin/codex-healthkit check

JSONで見たい場合は、こう。

./bin/codex-healthkit check --json

Codex CLIのdoctor summaryも合わせて見たい場合は、optional modeを使う。

./bin/codex-healthkit check --with-codex-doctor

ただし、このmodeではCodex CLIを実行する。
jq も必要です。
Codex CLI側がprovider reachability checkを行う場合もある。

デフォルトモードとは違う。
ここは分けて考える必要があります。

最初に見るなら、まずは普通の check だけでいい。
出力を読んで、Safety 欄を見る。
そのうえで、共有する前に自分で中身を確認する。

そこまでがセットです。

Codexを使うほど、共有してよい情報を分ける必要が出てくる

Codexを毎日使うようになると、相談したい場面が増える。

doctorが失敗した。
sessionが増えている。
SQLite WALが大きい気がする。
CLIの挙動が変わった。

その時に、何を見せればよいか迷う。

全部貼れば早い。
でも、それは危ない。

transcript、auth、token、cookie、SQLite contents、account ID、email address。
このあたりは、記事にもissueにも貼るべきではない。

一方で、ファイルサイズ、件数、status summary、redacted doctor summaryくらいなら、相談の入口として使えるかもしれない。

その境界を自分で持つ。

codex-healthkit は、そのための道具です。

まとめ。AIエージェントの運用には、共有境界も含まれる

Codexを使い始めた頃は、モデルとpromptに目が向いていた。

でも、毎日使うようになると、見る場所が変わってくる。
ローカル環境。
履歴。
ログサイズ。
doctor。
共有してよい情報と、出してはいけない情報。

これは地味です。
でも、日常運用ではかなり大事なところだと思う。

codex-healthkit は、Codex環境の問題を自動で解決するツールではない。
便利なcleanup toolでもない。

まず状態を見る。
中身は読まない。
外に送らない。
共有前に確認しやすいreportを作る。

そのくらいの小さなCLIです。

AIエージェントを日常の作業場として使うなら、作業の渡し方だけでなく、環境の見方も整えておきたい。
プロンプトやモデルだけではなく、ローカル環境と共有境界まで含めて運用する。

今回作った codex-healthkit は、その最初の形です。

参考・出典

• Ishikawa-Hidekazu/codex-healthkit
• v0.1.0-alpha.1 release
• examples/report.redacted.md
• Safety boundary
• Usage guide

あわせて読みたい本

AIエージェントや生成AI時代の仕事の組み立て方を考えるときに、手元に置いておきたい本も置いておく。
プロンプトを頑張る話から、作業手順や運用を育てる話へ視点を移すときに相性がいい。