Sessions

A session is one continuous run of a single agent against a single repo. Every time you invoke agent-relay run, Agent Relay creates a new session, captures every turn as it happens, and persists the artifacts to disk under .agent-relay/sessions/. Nothing is uploaded — everything lives locally, inside the repo you ran from.

What gets captured

For every turn the agent takes, Agent Relay records four things:

1. The prompt sent to the agent (system + user content).
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 never loses work that already happened.

On-disk layout

Inside any repo where you've run Agent Relay:

.agent-relay/
  sessions/
    01J9X3M7K5VBHQEN6T2F4D8RPZ/      # ULID — sortable by time
      meta.json                       # agent, command, 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.json                     # written at handoff (see 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 — agent-relay run is currently executing. Turn artifacts are written as they happen.
• checkpointed — the run hit a handoff condition (rate limit, manual stop, or completion). A resume.json is 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