# 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:

```fish
npx codex-recall@latest
```

Then open the local URL it prints, usually:

```text
http://127.0.0.1:32117
```

If you want to install it globally:

```fish
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:

```fish
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:

```text
~/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:

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

To clear the cache:

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

To use a different Codex home or cache directory:

```fish
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

```fish
npm install
npm run check
```

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