docs(history): document the offline reader next to codeman agent

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.
This commit is contained in:
Aamer Akhter committed 2026-10-24 23:00:50 -04:00
1 parent 002d876556
commit 44fa2d4757
8 files changed
+142 -100

No files matched your search

+6 -2
View File
@@ -123,8 +123,11 @@ message a worker directly instead of typing into its terminal.
## What it will and will not do
- **It self-gates.** Outside a Codeman session (`CODEMAN_MUX` unset) it refuses to act and
never guesses an API URL, so a global install costs an unrelated agent session nothing.
- **It self-gates.** Outside a Codeman session (`CODEMAN_MUX` unset) it refuses every live
API operation and never guesses an API URL, so a global install cannot drive a server it
is not part of. The one exception is reading saved Codex conversations with
`codeman history read` (see [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent#reading-saved-codex-conversations)),
a local, read-only command that needs no server or session.
- **Unprompted, it may only** start sessions, prompt them, and delete the ones **it created
in that conversation, by exact id**, behind a guard that refuses to delete the agent's own
session.
@@ -153,6 +156,7 @@ The skill checks for both and says so instead of acting.
| [`reference/recipes.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/recipes.md) | Worked flows: claude, DeepSeek Harness and shell workers, fan-out, watching a blocked worker, messaging. Loaded on demand. |
| [`reference/endpoints.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/endpoints.md) | Endpoint tables, error codes, the signals each mode emits, capacity limits. Loaded on demand. |
| [`reference/messaging.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/messaging.md) | Talking to claude workers directly through Claude Code's cross-session messaging. Loaded on demand. |
| [`reference/history.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/history.md) | Reading saved Codex conversations offline with `codeman history read`: selectors, filters, forks, budgets. Loaded on demand. |
Only `SKILL.md` sits in the agent's context; the references load when a job needs them, so a
quick run stays quick.
@@ -70,6 +70,32 @@ codeman agent rm "$SID" # any session except t
- **Exit codes** are the same for every verb: `0` done, `1` error, `2` timeout, `3` the
worker exited, `4` refused. `--json` prints the response's `data`.
## Reading saved Codex conversations
`codeman history read` is the one command here that needs no server and no Codeman
session: it reads Codex's own saved rollouts (`$CODEX_HOME/sessions`, else
`~/.codex/sessions`) from disk and writes nothing.
```bash
codeman history read --session-id 019fc604 # one conversation, by id or 8+ character prefix
codeman history read --root-session-id <uuid> --topic auth # it and every sub-agent or fork under it
codeman history read --file /path/to/rollout.jsonl --format text
```
- **Filters** keep whole user/assistant turns: `--topic` is a literal, case-insensitive
match, and `--after`/`--before` are inclusive UTC dates.
- **Forks and sub-agents**: a child's copy of its parent's history is dropped, so every
record belongs to the thread that wrote it.
- **`complete: false`** in the JSON means the evidence is partial: a store file that could
not be attributed, a record a running Codex is still writing, an ancestor not found.
- **Budgets** fail closed and are raisable: `--metadata-bytes` (attributing the store,
default 1 GiB), `--max-entries` (65536), `--scan-bytes` (the selected transcripts,
16 MiB) and `--max-bytes` (output, 8192). `--json` and `--format text` together are an
error.
The full reference ships with the skill as
[`reference/history.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/history.md).
## The MCP server
`codeman mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server, so any MCP
+1 -1
View File
@@ -42,7 +42,7 @@ codeman web # then open http://localhost:3000
**Driving it from code**
- [The Codeman Skill](Codeman-Skill) - one prompt, a whole crew: an agent starting and supervising worker sessions.
- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the `codeman agent` commands, the MCP server, wait primitives.
- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the `codeman agent` commands, the MCP server, wait primitives, reading saved Codex conversations offline.
- [HTTP API](HTTP-API) - the envelope, auth, the endpoint map, SSE events.
- [Hooks And Integrations](Hooks-And-Integrations) - events flowing back into Codeman.