From 7840abdd72e7b638ff402d04463d33415bc27dd4 Mon Sep 17 00:00:00 2001 From: Hai Huang Date: Tue, 17 Nov 2026 11:12:00 -0500 Subject: [PATCH] docs: Show agentop import to new users The agentop import reference was complete, but no entry point for a new user linked to it. The root README, the docs index, and the Claude Code, Codex and Bob guides did not mention it. - Add one paragraph to the root README quick start, with --dry-run. - Add a row to the docs index. - Add an "Import history" section to the Claude Code, Codex and Bob guides, in the same form as the Pi guide. - In the agentop README, name all five agents in the pricing sentence. Assisted-By: Claude (Anthropic AI) Signed-off-by: Hai Huang --- README.md | 4 ++++ cmd/agentop/README.md | 4 ++-- docs/README.md | 1 + docs/agents/bob.md | 15 +++++++++++++++ docs/agents/claude-code.md | 15 +++++++++++++++ docs/agents/codex.md | 16 ++++++++++++++++ 6 files changed, 53 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b37485e3c..331d5589b 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,10 @@ Setup asks once before changing anything. If something looks wrong, `agentop doc names the fix. To move to a newer release later, run `agentop update`. Can't reach rossoctl.dev? The same script is [in this repo](https://raw.githubusercontent.com/rossoctl/cortex/main/scripts/install.sh). +Used your agent before Cortex? `agentop import` adds its past sessions and their +cost from the transcripts on disk. Run `agentop import --dry-run` first to count +them. See [Importing agent history](./cmd/agentop/README.md#importing-agent-history-agentop-import). + ## What you can do with it **See where your tokens go.** Every session's tokens, cost and context fill, live. diff --git a/cmd/agentop/README.md b/cmd/agentop/README.md index c54744a7c..76fac1538 100644 --- a/cmd/agentop/README.md +++ b/cmd/agentop/README.md @@ -837,8 +837,8 @@ counted again, because the erase kept the ledger rows. An imported session has `(*)` before its title in the sessions pane. When the terminal is too narrow for TITLE, `(*)` is before its id. Its events show `n/a` for status, duration, bytes, host and plugin, because the -proxy did not see them. Tokens and cost show values. A Claude Code turn is priced -at today's rates. A Bob turn shows Bob's own cost. +proxy did not see them. Tokens and cost show values. A Claude Code, Codex, +OpenCode or Pi turn is priced at today's rates. A Bob turn shows Bob's own cost. ## Panes diff --git a/docs/README.md b/docs/README.md index 8f207cab5..81ff42f4e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ holds the repo-level pieces; this file is the index. | Customize Cortex with a small Python or shell script | [`script-plugin.md`](script-plugin.md) | | Run an agent on a local model, or switch inference servers | [`laptop-local-model.md`](laptop-local-model.md) | | Use the `agentop` TUI | [`cmd/agentop/README.md`](../cmd/agentop/README.md) | +| Add your agent's sessions from before Cortex | [`agentop import`](../cmd/agentop/README.md#importing-agent-history-agentop-import) | | Export sessions to files | [`session-dump.md`](session-dump.md) | | Export the archive for offline analysis (content-free records) | [`session-export.md`](session-export.md) | | Walk through exporting and analysing it, with the traps | [`session-export-guide.md`](session-export-guide.md) | diff --git a/docs/agents/bob.md b/docs/agents/bob.md index c24bef880..c5d142935 100644 --- a/docs/agents/bob.md +++ b/docs/agents/bob.md @@ -162,6 +162,21 @@ Bob/User/settings.json`). Elsewhere `--settings PATH` is required rather than guessed — writing a proxy setting into a file nothing reads is a silent no-op, which is worse than a refusal that names the flag. +## Import history + +`agentop import --agent bob` adds the Bob tasks from before Cortex to the +session history and the cost ledger. It reads `~/.bob/db/bob.db` through the +`sqlite3` program, so `sqlite3` must be on `PATH`. It covers Bob Shell and Bob +IDE, and it does not write to the database. + +- One root task and its child tasks make one session. +- The import skips a session that Cortex captured live. +- A turn keeps Bob's own cost. + +Flags and output: +[`agentop import`](../../cmd/agentop/README.md#importing-agent-history-agentop-import). +Rules: [`POST /v1/import`](../session-api.md#post-v1import--transcript-import-laptop-only). + ## Subagents and subtasks Bob can start child tasks. A subagent runs beside its parent. A subtask runs in diff --git a/docs/agents/claude-code.md b/docs/agents/claude-code.md index a8d2c1938..af691f29c 100644 --- a/docs/agents/claude-code.md +++ b/docs/agents/claude-code.md @@ -230,6 +230,21 @@ output limit lowered. The agent's own view of the conversation is not changed. S model list, that request is routed like the rest, so the picker can show, say, `glm-5.3`. A name chosen there goes to the server as it is, like any other. +## Import history + +`agentop import --agent claude-code` adds the Claude Code sessions from before +Cortex to the session history and the cost ledger. It reads the transcripts +under `~/.claude/projects`, or under `$CLAUDE_CONFIG_DIR/projects` when that variable is +set in the proxy's environment. + +- One session transcript and its subagent transcripts make one session. +- The import skips a session that Cortex captured live. +- A turn is priced at today's rates. + +Flags and output: +[`agentop import`](../../cmd/agentop/README.md#importing-agent-history-agentop-import). +Rules: [`POST /v1/import`](../session-api.md#post-v1import--transcript-import-laptop-only). + ## Verified depth Tested live on 2026-10-05 with Claude Code 2.1.286 on macOS 26.6.2 (arm64), Cortex built diff --git a/docs/agents/codex.md b/docs/agents/codex.md index 8736aa81a..a2aeac883 100644 --- a/docs/agents/codex.md +++ b/docs/agents/codex.md @@ -434,6 +434,22 @@ Worth knowing for anyone changing this: `tool-prune` and `inference-parser` keep **separate** suffix lists, and only the parser's recognises `/responses`. The drift is silent — the parser reads a Responses request that the pruner skips as "not inference". +## Import history + +`agentop import --agent codex` adds the Codex sessions from before Cortex to the +session history and the cost ledger. It reads the rollout files under +`~/.codex/sessions`, or under `$CODEX_HOME/sessions` when that variable is set +in the proxy's environment. + +- The root rollout of a session and the rollouts of its subagents make one + session. +- The import skips a session that Cortex captured live. +- A turn is priced at today's rates. + +Flags and output: +[`agentop import`](../../cmd/agentop/README.md#importing-agent-history-agentop-import). +Rules: [`POST /v1/import`](../session-api.md#post-v1import--transcript-import-laptop-only). + ## Verified depth Tested live with Codex 0.160.1 on macOS 26.3 (arm64), against the real ChatGPT backend,