Building tooling on ~/.codex rollout files — which behaviors are safe to design against?
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 125k
- Forks
- 19.4k
- PR merge metrics
- PR metrics pending
Description
Hi team — I write tooling that reads Codex CLI session files after runs finish, and I'd rather ask than assume. Nothing in the current docs (developers.openai.com/codex: app-server, noninteractive, cli/reference, config-reference, sdk) seems to state what a downstream consumer may rely on, so I'm hoping you can fill in the blanks — or confirm there are no guarantees, which is equally useful to know.
My setup, for context:
- ChatGPT desktop app (Codex) 26.903.71938 / build 8576, macOS
- session data under ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
- use case: a compliance-sensitive pipeline that archives and later re-reads turn records
| Area | What I'd like to know |
|---|---|
| Status of the rollout files | Supported record surface with a versioned schema and changelog — or internal detail that may change silently? |
| Turn completion marker | Is there a specific record (event type/name) that signals a turn finalized successfully, and when is it written relative to the turn's effects? |
| Crash / power loss | Are writes flushed or committed at defined points (fsync, atomic rename, WAL)? After a crash, can the final record be missing or torn while earlier ones survive? |
| Re-reading a past turn | Supported path to fetch one historical turn's completion record outside the live session — app-server read API (thread/turn/item IDs, "full" item data), codex resume, or something else — and is it documented as reading the on-disk store? |
| Record identity | Do records have stable IDs that survive later retrieval and app/CLI upgrades, and are written records treated as immutable? |
A doc link or a short per-row reply both work for me. And if the honest answer to any row is "no guarantee", please say so plainly — that tells me to build my own retention layer instead of trusting yours.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the listed Codex documentation areas and the ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl path. Map each table row to an explicit supported guarantee or an explicit absence of guarantee, including completion records, crash behavior, historical retrieval, identity, and immutability.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, cli, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100