mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-17 11:49:33 +01:00
Replace docs/offline-history.md, which repeated the skill reference and was linked from nowhere, with a README section and a wiki section beside the codeman agent commands. Bring the skill reference, its plugin mirror, the Codeman Skill wiki page and the changeset in line with the reader: forks, the separate budgets and their flags, UTC dates, phases and complete:false.
78 lines
4.4 KiB
Markdown
78 lines
4.4 KiB
Markdown
# 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, unreadable directories, missing
|
|
ancestors, or an inherited copy whose end could not be found or proven. 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. 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:
|
|
|
|
| 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 | 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.
|