After a few months of using Codex every day, the thing I worry about has changed. At first it was model choice and prompt wording. Once it became part of my daily work, a different question showed up: is my local environment actually fine?
How large have the session logs grown? Is the SQLite WAL spiking? And when something breaks and I want to ask for help, which parts of my local state are safe to paste into an issue, and which parts must never leave my machine?
I used to check this by hand. Now I run a small CLI I wrote for it: codex-healthkit. This is the record of why I built it and what I deliberately left out.
Originally published in Japanese on July 6, 2026, against v0.1.0-alpha.1. This English version was written in September 2026 and re-checked against v0.4.1. Note that a plain git clone checks out the development branch rather than a release — pin a tag if you want the published revision. This is a personal open-source project and is not affiliated with OpenAI.
Daily use shifts your attention away from model quality
If you use Codex occasionally, what matters is answer quality and speed. Which model to pick, which prompt gets your intent across, how much you can delegate.
That stopped being the whole picture for me. Codex is no longer a thing I consult now and then. Blog drafts, WordPress checks, GitHub repository cleanup, thread handoffs between AI agents, post-publish syncing. A large share of my work now passes through it, and I run a Mac mini as an always-on machine dedicated to that work.
At that point the conversation with the model is only half of the operation. The other half is the local environment it runs in. Does codex doctor pass? How many session files have accumulated? Has the SQLite WAL grown unexpectedly? Before I open an issue or ask someone for help, how much of that am I allowed to share?
Leaving those questions vague while depending on the tool daily felt uncomfortable. The more useful it becomes, the more the environment around it deserves attention.
From manual checks to a small CLI
I had already done this manually: check codex --version, read codex doctor --summary, look at the size of active and archived sessions, check the SQLite log file sizes. That alone tells you a lot.
It was just tedious to repeat. I forgot the commands. The things worth looking at were scattered across directories. And when something did break, I hesitated over what was safe to paste and what was not.
What I needed was not a full monitoring suite. Not a usage dashboard, not an automatic cleanup tool, not a transcript parser. Just a small CLI that summarizes local state in a form that is easy to share.
It reads metadata, not contents
The scope is deliberately narrow. codex-healthkit looks at local file metadata: sizes, counts, existence, and status summaries. By default it does not even invoke the codex command. Using the official doctor is an opt-in mode.
What it checks:
- Whether the
codexcommand exists - Active sessions directory: total size and
.jsonlcount - Archived sessions directory: total size and
.jsonlcount - Quarantine directory size
- File sizes of
logs_2.sqlite,logs_2.sqlite-shm, andlogs_2.sqlite-wal - A size-only check for an unusually large SQLite WAL
- Optionally, the Codex CLI version
- Optionally, a redacted summary of
codex doctor --json
What it never reads: credentials, token files, cookies, localStorage, OS credential stores, SQLite contents, session transcript contents, account IDs, email addresses, and browser profiles. It also does not perform cleanup, deletion, or archiving, and it never uploads a report anywhere.
One distinction is worth stating precisely. In the default mode it does not execute the codex command at all. In the opt-in --with-codex-doctor mode it does run codex doctor --json and parses that JSON with jq in order to extract a redacted summary. The raw doctor output is never written to the report, but it is read in memory during that run, and the Codex CLI itself may perform a provider reachability check as a side effect.
That second list mattered more than the first. When you build a health check it is tempting to inspect everything. In an AI agent workspace, choosing not to look is part of the design. Reading sensitive data in order to produce a shareable report defeats the purpose.
The example output is redacted on purpose
The repository ships examples/report.redacted.md rather than a real local report:
# 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`What matters here is not my actual file counts. It is the shape of the report and the safety boundary printed alongside it. I am not claiming the tool is provably safe. The goal is a low-risk report you can verify yourself before sharing it.
What it is not
To avoid misunderstanding: codex-healthkit is not a usage dashboard, not a quota tracker, not a session cleaner, and not a transcript analyzer. The README keeps an explicit non-goals list covering account switching, transcript parsing, usage estimation, automatic cleanup, background monitoring, and npm package distribution.
The reasoning is simple. Make a tool convenient too early and its scope widens. Widen the scope and you start wanting to read things you should not read. When you touch a Codex local environment, start with a narrow boundary.
Trying it
# pin the published release
git clone --branch v0.4.1 --depth 1 https://github.com/Ishikawa-Hidekazu/codex-healthkit.git
cd codex-healthkit
./bin/codex-healthkit checkFor JSON output, add --json. As of v0.4.1 the optional modes are --with-codex-version, --with-codex-doctor, --with-runtime, and --compare <previous-report.json>. Of these, --with-codex-doctor is the one that changes the boundary: it executes the Codex CLI, requires jq, and may trigger a provider reachability check on the Codex side. --compare reads a previous JSON report you supply and also needs jq. Treat those separately from the default mode.
For a first run, plain check is enough. Read the output, look at the Safety section, and review the content yourself before sharing it anywhere. That review step is part of the workflow, not an optional extra.
MIT licensed. Tested on macOS and Linux. Windows is not supported by this Bash implementation.
Heavy use makes the sharing boundary a real problem
The more you use Codex, the more often you want to ask someone about it. The doctor failed. Sessions keep growing. The SQLite WAL looks large. CLI behavior changed after an update.
Pasting everything is fastest and also reckless. Transcripts, auth files, tokens, cookies, SQLite contents, account IDs, and email addresses do not belong in a blog post or a GitHub issue. File sizes, counts, a status summary, and a redacted doctor summary are usually fine as a starting point for a question.
Drawing that line yourself is the actual skill. codex-healthkit is just a tool that makes drawing it easier.
Running an AI agent includes running its boundary
When I started with Codex, I was looking at models and prompts. Using it daily moved my attention to the local environment: history, log sizes, the doctor, and which information is safe to share.
It is unglamorous work, and it is where daily operation actually lives. codex-healthkit does not fix your Codex environment automatically and it is not a convenience cleanup tool. It looks at state, does not read contents, sends nothing outward, and produces a report you can check before sharing.
If an AI agent is part of your daily workspace, it is worth setting up how you inspect that workspace, not just how you hand work to the model.