Production-ready CLI tools and a Codex skill for keeping long OpenAI Codex threads healthy.
Current version: 1.0.0
codex-thread-tools works with local Codex session JSONL files under
~/.codex/sessions/.
Codex compaction helps long conversations continue, but it does not make an oversized local thread a good place to keep all project memory. This repo gives you practical tools for checking thread health, preserving durable context, archiving old session data, and recovering from oversized-session problems.
The 1.0.0 release marks the CLI surface as production-ready. Stable scripting
should use --json; human-readable output may keep improving over time.
Run once with npx:
npx codex-thread-tools healthInstall globally:
npm install -g codex-thread-tools
codex-thread-tools healthInstall the bundled handoff skill:
codex-thread-tools install-skillThen, from any Codex thread:
Use codex-thread-handoff.
Python 3 must be available on your PATH. The npm package is a wrapper around
the bundled Python tools.
| Tool | What it does | Main command |
|---|---|---|
| Health check | Reports whether Codex project threads look ok, risky, or ready for handoff. | codex-thread-tools health |
| Handoff summary | Creates a concise, redacted summary draft from one session file. | codex-thread-tools handoff-summary <session.jsonl> |
| Session archive | Copies old session JSONL files to external storage with verifiable manifests. | codex-thread-tools session-archive |
| Visual archive | Copies screenshots and videos out of old threads into storage you choose. | codex-thread-tools visual-archive |
| Handoff skill | Writes durable project context before starting a fresh Codex thread. | codex-thread-tools install-skill |
| Recovery starter | Helps inspect and back up damaged or oversized session files. | codex-thread-tools recover |
Read the Documentation index for full command usage and maintainer notes.
| Guide | Covers |
|---|---|
| Installation | npx, global npm install, source checkout, and skill install. |
| Thread health | Health reports, display modes, risk domains, token reports, and JSON output. |
| Handoff workflow | Repo-backed continuity, redacted summaries, and handoff markers. |
| Session archive | Moving old JSONL sessions to external storage and pruning verified local copies. |
| Visual archive | Preserving screenshots and videos outside oversized threads. |
| Recovery | Inspecting and backing up damaged sessions. |
| Compaction | How Codex compaction differs from handoffs and archives. |
| Development | Tests, fixtures, package checks, and repo hygiene. |
| Publishing | GitHub release and npm Trusted Publishing flow. |
| Task | Command |
|---|---|
| Project health report | codex-thread-tools health |
| One session health report | codex-thread-tools health check <session.jsonl> |
| Token usage report | codex-thread-tools health tokens |
| Redacted handoff summary draft | codex-thread-tools handoff-summary <session.jsonl> |
| Record handoff marker | codex-thread-tools handoff-marker record ... |
| Plan old session archive | codex-thread-tools session-archive plan ... |
| Archive old session files | codex-thread-tools session-archive archive ... |
| Verify session archive | codex-thread-tools session-archive verify --manifest <manifest.json> |
| Prune archived local sessions | codex-thread-tools session-archive prune-local --manifest <manifest.json> --confirm-prune-local |
| Scan visual references | codex-thread-tools visual-archive scan <session.jsonl> |
| Archive visual references | codex-thread-tools visual-archive archive <session.jsonl> ... |
| Inspect a damaged thread | codex-thread-tools recover inspect <session.jsonl> |
Use compaction to keep working inside the current thread.
Use a handoff when the thread is getting large, has compacted several times, or contains decisions that should survive outside the chat log.
Use archive tools when old sessions or visuals should be preserved somewhere other than your live Codex session folder.
Use recovery tools only after a thread is already hard to load, has disappeared from the sidebar, or has hit a compaction/context error.
MIT. See LICENSE.