exploring-codex-sessions
Installation
SKILL.md
Exploring Codex Sessions
Set CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}" and CODEX_DB_ROOT="${CODEX_SQLITE_HOME:-$CODEX_ROOT}". Codex CLI stores sessions as JSONL rollouts under $CODEX_ROOT; rollouts are canonical and SQLite is rebuildable. Writers are mixed; persistent exec is the proven paginated-default path.
Storage locations
| Path | What it holds |
|---|---|
$CODEX_ROOT/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl |
Full session transcripts. Date dirs use local time |
$CODEX_ROOT/archived_sessions/rollout-*.jsonl |
Archived sessions (flat, no date dirs, via codex archive) |
$CODEX_DB_ROOT/state_5.sqlite |
threads table: metadata index (cwd, preview, first_user_message, title, name, git info, history_mode, archived flag). Treat as cache — rebuilt from rollouts |
$CODEX_DB_ROOT/thread_history_1.sqlite |
Rebuildable transcript-item projection; contains item JSON but is not canonical |
$CODEX_DB_ROOT/queue_1.sqlite |
Pending user submissions; writing to it changes queue state |
$CODEX_ROOT/history.jsonl |
User-typed prompts: {"session_id", "ts" (unix sec), "text"}. Check its mtime first — it can silently stop being appended (see pitfall) |
$CODEX_ROOT/session_index.jsonl |
Thread names: {"id", "thread_name", "updated_at"}, last entry wins |
$CODEX_ROOT/config.toml |
[history] persistence = "save-all"|"none" |
Sessions are never auto-deleted (codex archive / codex delete are manual). Rollouts may be zstd-compressed to .jsonl.zst; search them when zstdgrep or zstdcat is available. The SQLite root follows CODEX_SQLITE_HOME, then CODEX_HOME; do not assume CODEX_HOME relocates every store. session_index.jsonl is an append-only compatibility index; prefer SQLite where available.