exploring-codex-sessions
Exploring Codex Sessions
Use the narrowest read-only capability that answers the request. In Codex Desktop, list_threads, read_thread, and list_archived_threads can list current or archived threads and return recent status or bounded turn summaries. App-server clients can use thread/list, thread/read, thread/turns/list, and thread/items/list for metadata and history. Use these interfaces first for ordinary discovery and reading; inspect their available fields and pagination before relying on them. They do not necessarily expose the underlying rollout or every historical item.
Use raw storage when native history APIs cannot reach the target or do not contain the needed content, or when the user explicitly asks for raw storage-level detail. Do not use resume merely to inspect a thread. 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" |