Codex Recall

Find old Codex conversations that no longer show up clearly in the Codex Desktop sidebar.

Codex Recall runs on your own machine, reads your local Codex history, and opens a small browser UI for searching and inspecting past sessions. It is useful when you remember a project, command, file path, topic, or rough phrase, but not the exact thread title.

What It Helps With

• Find a past Codex thread by project folder.
• Search old conversations by words, commands, file paths, or error messages.
• Browse active and archived local sessions in one place.
• Open a session detail page and inspect the transcript.
• Inspect the thread id, cwd, JSONL path, sources, and transcript.
• Copy a fish-friendly resume command for continuing a session from the terminal.
• Experimentally restore an archived or old session toward the Codex App sidebar.
• Download a transcript as plain text.

Codex Recall's search and browsing path is read-only. The optional experimental Restore visibility action writes to local Codex state after creating a backup, so use it only when you want to repair sidebar visibility for a specific session.

Quick Start

Run it with npx:

npx codex-recall@latest

Then open the local URL it prints, usually:

http://127.0.0.1:32117

If you want to install it globally:

npm install -g codex-recall
codex-recall

If the default port is busy, Codex Recall will try the next available port. You can also choose the starting port:

CODEX_RECALL_PORT=34000 codex-recall

What You Can Search

Codex Recall indexes local Codex session data and lets you search:

• session titles
• project paths / cwd
• user messages
• assistant messages
• commands
• file paths
• thread ids
• active and archived transcripts

The UI also shows diagnostics so you can see whether Codex Recall found your database, session index, active transcripts, and archived transcripts.

Privacy And Safety

Codex Recall stays local by default:

• binds to 127.0.0.1
• does not upload your sessions
• does not include telemetry
• does not require API keys
• does not write to ~/.codex while searching or browsing
• creates a local backup before the experimental Restore visibility action writes Codex state

It reads these local Codex files:

• ~/.codex/state_5.sqlite
• ~/.codex/session_index.jsonl
• ~/.codex/sessions/**/*.jsonl
• ~/.codex/archived_sessions/**/*.jsonl

The experimental Restore visibility action uses the local codex unarchive command when needed, updates ~/.codex/state_5.sqlite and ~/.codex/session_index.jsonl for the selected thread, and may move that thread's transcript from ~/.codex/archived_sessions back to ~/.codex/sessions. Preview does not write files. Each real restore creates a fresh timestamped backup under:

~/Library/Application Support/codex-recall/backups

After a successful restore, restart Codex App so its sidebar reloads local session state.

Your transcripts may contain private project details, file paths, prompts, commands, and copied output. Treat the local browser as sensitive even though it only runs on localhost.

Cache

Codex Recall writes a separate search cache here:

~/Library/Application Support/codex-recall/index.json

To clear the cache:

rm -rf ~/Library/Application\ Support/codex-recall

To use a different Codex home or cache directory:

CODEX_HOME=/path/to/.codex codex-recall
CODEX_RECALL_CACHE_DIR=/tmp/codex-recall-cache codex-recall

Notes

Codex's local storage format is not a public stable API. If Codex changes how it stores local sessions, Codex Recall may need an update.

Development

npm install
npm run check

npm run check runs lint, unit tests, build, browser tests, and an npm package smoke test.