Codeman/skills/codeman/reference/history.md

# Saved Codex history (offline)

Use `codeman history read` for retained local Codex JSONL transcripts. This command
works outside a managed session and never calls the HTTP API. Do not bootstrap
API credentials or require `CODEMAN_MUX` for this read-only job.

Choose exactly one selector:

```bash
codeman history read --file /path/to/rollout.jsonl
codeman history read --session-id aaaaaaaa --sessions-root /path/to/sessions
codeman history read --root-session-id aaaaaaaa-1111-4111-8111-111111111111 \
  --topic 'authentication' --after 2026-10-01 --before 2026-10-24 \
  --max-bytes 65536
```

`--session-id` accepts a native conversation UUID or unique prefix of at least
8 characters; identity comes from metadata, not filenames. `--root-session-id`
requires a full native UUID and includes transitive descendants found in metadata
(spawned sub-agents and forks). The default store is `$CODEX_HOME/sessions`, or
`~/.codex/sessions` when unset; a store directory that is itself a symlink is
followed, links inside it are skipped. `--file` selects one file and does not
search for its ancestors or children.

Topic matching is a case-insensitive literal substring. Dates are inclusive
`YYYY-MM-DD` bounds compared as UTC calendar dates. Each filter selects whole
user/assistant turns; a turn is retained if it has a date match and a topic match,
which may be different messages in that turn. Tool calls/results and injected
context (rows Codex adds that start with `#` or `<`, such as AGENTS.md and
`<environment_context>`) are omitted. Adjacent duplicate native representations
are collapsed; repeated messages from the same representation are retained.

A forked or spawned thread's file starts with a copy of its parent's history. That
copy is dropped (it is in the parent's own file), so each record belongs to the
thread that wrote it. A later `session_meta` for any thread that is not a declared
ancestor still refuses the file.

JSON is the default (`--json` or `--format json`); `--format text` prints one block
per record. `--json` together with `--format text` is an error.
Results identify source paths, native session/root IDs, timestamps, roles and phases,
plus scan counters and `complete`. `phase` is Codex's own (`commentary` or
`final_answer`) on assistant records and `null` on user records or when none was
recorded. A root ID is `null` when ancestry cannot be proven.
Report that uncertainty; never relabel the queried child as its own root.
`complete: false` reports malformed or partial records (a running Codex may be
mid-write), skipped links, unattributed files, compressed rollouts, unreadable
directories, missing ancestors, or an inherited copy whose end could not be found
or proven (including when the parent's file is present but cannot be read). It
does not prove the store includes every conversation ever created, and a filtered
result is only evidence for its selected scope.

Reads require regular UTF8 files and reject final-component symlinks, conflicting
metadata, ambiguous IDs, cyclic ancestry and invalid selectors. A store file that
cannot be attributed (invalid UTF8 in its head, no metadata in its first 128 KiB,
changing while its head is read) is counted in `unattributedFiles` instead of
failing the lookup. Codex's optional rollout compression rewrites cold rollouts to
`*.jsonl.zst`; those are not read. Each is counted in `compressedFiles` (one whose
plain `.jsonl` sibling exists is skipped, as Codex skips it), and a lookup that
misses names them. A compressed file passed to `--file` is refused; read a
decompressed copy instead (`zstd -dc <file> > copy.jsonl`). A selected rollout
that a running Codex is appending to is read as a snapshot up to its last complete
line; one that was replaced or truncated fails. Parent directories of an explicitly supplied path must be trusted; this is
not a filesystem sandbox.

Budgets, each failing with an error rather than a partial answer. Every flag is
validated before the first file is read, and only plain decimal integers are
accepted:

| Flag | Bounds | Default | Maximum |
| ---- | ------ | ------- | ------- |
| `--metadata-bytes` | head reads attributing every rollout in the store | 1 GiB | 16 GiB |
| `--max-entries` | directory entries visited | 65536 | 1048576 |
| `--scan-bytes` | the selected transcripts, plus any parent file read to prove where a copy ends (each file charged once) | 16 MiB | 256 MiB |
| `--max-bytes` | output, including the final newline | 8192 | 1048576 |

Each rollout's `session_meta` carries Codex's base instructions (about 20 KiB), so
attributing a store costs about that much per rollout, charged to
`--metadata-bytes`, never to `--scan-bytes`. Directory depth is capped at 8 (Codex
writes `YYYY/MM/DD`). Output is never silently truncated or split into partial
JSON or turns. Narrow the store/filters or explicitly raise the relevant budget.
Missing evidence is an error, not an empty success.

This command does not inspect live panes, stage prompts, submit input or manage
sessions. For live operations return to the managed-session guard in the skill.