codex-session-toolkit

Utilities for inspecting and maintaining local Codex app state on macOS.

The toolkit is distributed as macOS arm64 binaries attached to GitHub Releases. Each Release Asset contains one Utility binary.

Download

Open the GitHub Releases page and download the archive for the utility you want to run:

• thread-archiver_<version>_darwin_arm64.tar.gz
• codex-db-state_<version>_darwin_arm64.tar.gz

The release also includes SHA256SUMS. Download it into the same directory as the archive and verify the selected archive checksum:

grep 'thread-archiver_<version>_darwin_arm64.tar.gz' SHA256SUMS | shasum -a 256 -c -

Then unpack the selected archive:

tar -xzf thread-archiver_<version>_darwin_arm64.tar.gz
cd thread-archiver_<version>_darwin_arm64

Use the matching codex-db-state_<version>_darwin_arm64.tar.gz name in these commands when downloading codex-db-state. Run the binary from the unpacked directory.

Requirements

• macOS on Apple Silicon.
• A local Codex home directory, normally ~/.codex.
• codex on PATH when running thread-archiver --dry-run=false.
• lsof on PATH when running codex-db-state.

Commands

thread-archiver

Archives selected active Codex threads through the official codex app-server JSON-RPC API and writes an incremental JSON manifest. The default mode is a dry run.

./thread-archiver
./thread-archiver --dry-run=false

See cmd/thread-archiver/README.md for selection rules, validation behavior, manifest fields, and operational notes.

codex-db-state

Shows a read-only terminal UI summary of Codex state_5.sqlite and logs_2.sqlite, including database file sizes, thread/log counts, time ranges, and open file handles.

./codex-db-state
./codex-db-state --codex-home ~/.codex

See cmd/codex-db-state/README.md for the database layout and read-only behavior.

Safety Notes

These tools inspect or request changes to local Codex state. Review the selected Codex home and database path before running them against real data.

• codex-db-state is read-only. It opens state_5.sqlite and logs_2.sqlite in SQLite read-only mode to run integrity checks and summary queries.
• thread-archiver does not write SQLite directly, but with --dry-run=false it asks codex app-server to archive selected threads.
• Hidden fallback behavior is not used. Missing files, missing commands, failed checks, or unexpected archive validation results are reported as errors.

Dangerous maintenance scripts are documented separately in docs/maintenance.md.

Development

Development, testing, linting, and release-build notes live in docs/development.md.

License

This project is licensed under the MIT License. See LICENSE.