Sessions

A session is one continuous body of work against a single repo. In the interactive relay shell, the session can span multiple agents: prompts go to the active agent, /use can switch to another agent through a handoff packet, and automatic rate-limit handoff can continue the same lineage when hooks are wired.

Scriptable commands such as agent-relay run, agent-relay chat, and agent-relay race also create sessions. In every case, artifacts are persisted under .agent-relay/sessions/. Nothing is uploaded — everything lives locally, inside the repo you ran from.

What gets captured

For every turn Relay can observe, it records four things:

1. The prompt sent to the active agent.
2. The output the agent returned (text + tool calls + reasoning, when the provider exposes it).
3. stderr — anything the agent emitted to the standard error stream.
4. State — turn metadata: timestamp, token counts, tool-call outcomes, files touched, validation results.

These are written turn-by-turn, so a crash, kill signal, or rate-limit interruption does not lose work Relay already captured.

On-disk layout

Inside any repo where you've run Agent Relay:

.agent-relay/
  sessions/
    01J9X3M7K5VBHQEN6T2F4D8RPZ/      # ULID — sortable by time
      meta.json                       # objective, active agent, start/end time, status
      turns/
        001-prompt.md                 # what we sent
        001-output.md                 # what came back
        001-stderr.log                # any stderr from this turn
        001-state.json                # tokens, tools, files, validation
        002-prompt.md
        002-output.md
        ...
      resume/                         # agent-specific resume packets for handoffs
    01J9X9N7Q2C5VFGMP4HTSXKDBE/
      ...
  config.toml                         # optional, repo-local overrides

Session IDs are ULIDs so the directory listing is already in chronological order.

Reading sessions back

Because every artifact is a real file, you can use any tool you already trust. A few patterns that come up often:

cd .agent-relay/sessions
ls -t | head -n 1

Lifecycle

A session goes through three states:

• active — the REPL or a command-mode run is still working. Turn artifacts are written as they happen.
• checkpointed — the run hit a handoff condition (rate limit, manual switch, explicit handoff, or completion boundary). Resume packets are written and the session is ready to be picked up by another agent.
• completed — the agent finished cleanly. No resume packet exists; the session is read-only history.

The current state lives in meta.json under the status key.

Next