Skip to main content

​
Overview

Session handoff lets you pick up an agent session where it stopped. You can reopen it in the runtime it ran in, or continue it in a different one. For example, you can move a Claude Code session into Codex when you hit a rate limit, or give a stalled task to another agent without explaining it all again. Handoff reads each runtime’s own local session store, not Beacon’s runtime log. That store is what the runtime resumes from, and it keeps content the runtime log truncates. Every read is local and read-only. Nothing is uploaded, no runtime file is changed, and no command in the handoff path touches the network. Handoff supports Claude Code, Codex CLI, OpenCode, and Cline. See beacon handoff for the full command reference.

​
Workflow

  1. Find the session. beacon handoff list shows resumable sessions across every supported runtime, newest first. You can filter it by runtime or by directory.
  2. Summarize it. beacon handoff export writes a handoff brief. The brief is a Markdown summary of what the session asked for, what it changed, and where it stopped.
  3. Continue it. beacon handoff resume prints its plan, asks you to confirm, and launches the runtime in this terminal, in the session’s recorded directory.

​
Two ways to resume

Reopen natively. Beacon reopens the session with its full context when you continue in the same runtime, that runtime’s CLI can load the session, and the session file is still on this machine. This runs claude --resume, codex resume, opencode --session, or cline --tui --id. The session keeps its own id. Start a new session from a brief. Beacon starts a new session from a brief when you continue in a different runtime, when you pass --new, or when the session can’t be reopened natively. Subagent sessions and sessions known only from Beacon’s runtime log always take this path. Beacon writes the brief, then starts a new session whose first prompt names the brief by its path and asks the agent to confirm the task before it changes anything.

​
What a brief contains

A brief is a summary, not a full transcript:
  • The source runtime, session id, directory, branch, and last activity.
  • The first and latest requests, and the last agent message.
  • Files changed and recent commands, with exit codes where the runtime reports them.
  • The last 30 steps of activity, each cut to 1,200 characters.
Agent reasoning and file reads are left out. A brief is at most 48 KiB, and the oldest steps are dropped first to stay under that limit. If a session is no longer in its runtime’s store, Beacon builds the brief from the runtime log instead. That works for any runtime Beacon captured, but the log keeps less of each step, and the brief says so.

​
Linking sessions in telemetry

A session started from a brief has a new session id. To keep the two sessions connected, its first prompt ends with a handoff marker:
When Beacon records a prompt that carries this marker, it writes a session.handoff event alongside the usual prompt.submitted event. The event’s handoff.source_harness and handoff.source_session_id fields name the session it continues. Live hooks record the link as the prompt is sent. The claude, codex, opencode, and cline session-store syncs record it when they read the prompt back. This lets you follow one task across runtimes in the runtime log or a forwarded destination, and threat rules can match on e.handoff.*. The marker is text in a prompt, not a verified identity, and anyone can type it. The observed fidelity on the event means Beacon saw the marker. It does not mean that beacon handoff resume wrote it.

​
Safety boundary

  • Local and read-only. Handoff reads runtime session stores and never writes to them. No step contacts the network.
  • Redacted briefs. Every event goes through the same secret redaction and truncation as the runtime log before it reaches a brief.
  • Private files. Briefs are written to ~/.beacon/endpoint/handoffs, a 0700 directory, and each brief is a 0600 file, because briefs carry prompt text and command output. An existing brief is never overwritten.
  • Nothing on the command line. The brief is passed by path and never inlined into the launch command, which any local user can see in the process table.
  • No forged structure. Quoted content sits in code fences longer than any backtick run inside it, so text from a session can’t close its block and pass itself off as part of the brief.
  • Confirmation before launch. resume asks before it starts a runtime, and it launches without a terminal only with --yes. It stops if the session’s directory no longer exists, rather than starting somewhere else. Cline sessions are always started with --auto-approve false, because Cline approves every tool call by default.