Skip to content

Commit 6673fa0

Browse files
docs(codex): clarify rollout precedence and data paths
Scope plain-over-compressed precedence to one directory and state that sessions/ beats archived_sessions/ regardless of encoding. List every recursive rollout path, and attribute ordered parallel reads to loader.rs rather than ccusage-adapter-common. Reported by cubic on #1890. Co-authored-by: Henry Teo <[email protected]>
1 parent c06f96f commit 6673fa0

2 files changed

Lines changed: 8 additions & 5 deletions

File tree

‎docs/guide/codex/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Most users can start with unified reports such as `ccusage daily`. Add the `code
2323

2424
## Data Source
2525

26-
The CLI reads Codex session JSONL files, both plain `.jsonl` and Zstandard-compressed `.jsonl.zst`, located under `CODEX_HOME` (defaults to `~/.codex`). `CODEX_HOME` can be one directory or a comma-separated list of directories. For each entry, ccusage discovers `sessions/` and `archived_sessions/` independently, so an entry with only `archived_sessions/` still contributes archived Codex logs. When neither directory exists, the entry is read directly as a JSONL directory, which lets saved `codex exec --json` output live beside normal Codex homes. If the same relative JSONL path exists in both `sessions/` and `archived_sessions/` for one Codex home, the active `sessions/` copy wins so archived copies are not double counted. Compression does not change a session ID, and when a plain and compressed copy of the same rollout both exist, the plain copy is read and the compressed one is skipped, matching Codex.
26+
The CLI reads Codex session JSONL files, both plain `.jsonl` and Zstandard-compressed `.jsonl.zst`, located under `CODEX_HOME` (defaults to `~/.codex`). `CODEX_HOME` can be one directory or a comma-separated list of directories. For each entry, ccusage discovers `sessions/` and `archived_sessions/` independently, so an entry with only `archived_sessions/` still contributes archived Codex logs. When neither directory exists, the entry is read directly as a JSONL directory, which lets saved `codex exec --json` output live beside normal Codex homes. Compression does not change a session ID. Within one directory, when a plain and a compressed copy of the same rollout both exist, the plain copy is read and the compressed one is skipped, matching Codex. If the same relative rollout path exists in both `sessions/` and `archived_sessions/` for one Codex home, the active `sessions/` copy wins regardless of encoding, so archived copies are not double counted.
2727

2828
```bash
2929
CODEX_HOME="$HOME/.codex,$HOME/.codex-work,$HOME/codex-exec-logs" ccusage codex daily

‎rust/adapters/codex/README.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,16 @@ Anything that is not specific to this source belongs in `ccusage-core` or
2020

2121
## Data source
2222

23-
- `~/.codex/sessions/**/*.jsonl` and `*.jsonl.zst`
24-
- `~/.codex/archived_sessions/**/*.jsonl` and `*.jsonl.zst`
23+
- `~/.codex/sessions/**/*.jsonl`
24+
- `~/.codex/sessions/**/*.jsonl.zst`
25+
- `~/.codex/archived_sessions/**/*.jsonl`
26+
- `~/.codex/archived_sessions/**/*.jsonl.zst`
2527

2628
Record shapes, token mapping, and cost rules are documented in [`src/README.md`](src/README.md).
2729

28-
Uses `ccusage-adapter-common` for walking, size-balanced chunking, and ordered parallel
29-
reads; `reader.rs` streams `.jsonl.zst` rollouts through `zstd` without unpacking them to disk.
30+
Uses `ccusage-adapter-common` for walking and size-balanced chunking. `loader.rs` performs
31+
the ordered parallel reads, and `reader.rs` streams `.jsonl.zst` rollouts through `zstd`
32+
without unpacking them to disk.
3033

3134
## Public surface
3235

0 commit comments

Comments
 (0)