Recall and resume with sessions

Every agent run is captured. Pick up exactly where the last run left off.

Why sessions exist

An agent loses every byte of context the moment its process exits. Without persistence, the next run starts blind — you re-explain the repo layout, the half-finished refactor, the API quirk you spent twenty minutes diagnosing yesterday. The session log is the harness's memory. It records each turn, each tool call, each file edit, and keeps the record addressable by id.

Sessions are written automatically. You do not opt in. Every run of agents run or any wrapped agent CLI produces a session under ~/.agents/sessions/.

List recent runs

agents sessions
agents sessions --last 20

Bare agents sessions opens an interactive picker sorted by recency, with the agent name, the repo, the first user turn, and the duration in one row. --last 20 prints the same rows to stdout for piping into grep or fzf.

Read a specific run

agents sessions <id>
agents sessions <id> --markdown

The first form prints a concise summary — the user prompt, the assistant's final reply, the files edited, and exit status. The --markdown form prints the full transcript with tool calls and tool results in line order, suitable for a gist, a PR description, or piping into another agent as context.

Resume mid-flight work

agents sessions --active
agents run claude --resume <id> "follow-up instruction"

--active lists every agent currently running — terminal sessions, headless runs, team members. Pick the id you want to follow up on. --resume takes a finished session id and restarts the agent with the full prior conversation pre-loaded, then appends your new instruction as the next user turn. The agent does not re-read files it already knows; it picks up at the next decision.

Filter by topic or repo

agents sessions "stripe webhook retries"
agents sessions "oauth refresh" --include user,assistant

The query string runs a hybrid lexical and semantic search across every transcript. Lexical catches exact identifiers — function names, file paths, error strings. Semantic catches paraphrase — “the bug with token refresh failing on 401” surfaces the run where the agent fixed it, even if the transcript phrased it differently. --include user,assistant trims tool-call noise so the matches read as conversation.

Why this matters for the harness

A harness is the work you do so an agent never makes the same mistake twice. That requires evidence of the first mistake. When an agent fails partway — bad plan, wrong file, regression introduced — the transcript is the artifact you read to find the failure point. You do not re-derive it from memory. You open the run, quote the offending tool call, and write the rule into AGENTS.md so the next agent reads it before it tries the same thing.

Sessions are the harness's feedback loop. Without them you are guessing. With them you are reviewing.