Resuming a session

Every session Agent Relay captures is fully resumable from disk. There is no "stale after N hours" rule, no daemon to restart, no in-memory state that gets lost when you close the laptop. As long as .agent-relay/sessions/<id>/ still exists, you can pick the session back up.

This guide covers four resume situations you'll actually hit:

• The previous agent rate-limited and you want a fresh agent to continue.
• The previous agent crashed or you killed it with Ctrl-C.
• The task paused overnight and you're coming back tomorrow.
• The previous agent went off the rails and you want to rewind and try again.

Find the session you want

Every session is a directory under .agent-relay/sessions/ named with a ULID — directory listings are already in chronological order.

ls -t .agent-relay/sessions | head

If you know the rough timestamp or the task description, grep meta.json:

grep -l "failing auth tests" .agent-relay/sessions/*/meta.json

Case 1: Rate-limit handoff (the common case)

If the previous run hit a rate limit, Agent Relay already wrote a resume.json. Just launch the next agent with --resume:

agent-relay run x --resume "Continue from current state"

--resume with no --from flag picks up the latest session in the repo that has a resume.json. Use --from <session-id> to target a specific one.

Case 2: Recovering from a crash

If the agent process died mid-turn — kill signal, OOM, network blip — no resume.json was ever written. You have two options:

1. 1

   Force a checkpoint from disk

   Agent Relay can synthesize a resume packet from the last-completed turn's state.json:

   >_terminal

   agent-relay handoff --session <session-id> --reason "recovered from crash"

   The resulting resume.json won't include a next_task summary (the crashed agent never produced one), but every other field is reconstructed from disk.

2. 2

   Launch the resumer

   >_terminal

   agent-relay run c --resume --from <session-id> "Continue the task"

   Pass a manual prompt to substitute for the missing next_task field.

Case 3: Coming back the next day

No special command needed — just rerun with --resume. The session artifacts are sitting where you left them.

agent-relay run c --resume "What was the next step we were going to try?"

The new agent reads the resume packet at startup and has the full context of what was done yesterday before responding to your prompt.

Case 4: Rewinding to an earlier turn

Sometimes the agent went down a wrong path and you want to retry from turn 8 with different guidance. resume.json is just a JSON file — edit it:

1. 1

   Open the packet

   >_terminal

   $EDITOR .agent-relay/sessions/<session-id>/resume.json

2. 2

   Trim decisions and blockers

   Delete entries from decisions[] and blockers[] that came after the point you want to rewind to. Lower the turn_count. Update validation_state to reflect what was true at that earlier turn.

3. 3

   Rewrite next_task

   Replace next_task with the alternative direction you want the next agent to take.

4. 4

   Resume

   >_terminal

   agent-relay run c --resume --from <session-id> "Try this approach instead"

   The new session starts from your edited packet — not from the original end-of-session state.

Cross-machine resume

The whole session directory is portable. Copy .agent-relay/sessions/<id>/ to another machine, into a repo with the same git state, and resume there. The resume packet doesn't care which machine wrote it.

rsync -av .agent-relay/sessions/<id>/ remote:/path/to/repo/.agent-relay/sessions/<id>/
ssh remote
cd /path/to/repo
agent-relay run c --resume --from <session-id> "Pick up where we left off"

Next