Skip to main content

​
Command overview

beacon handoff finds the agent sessions stored on this machine so you can pick one up again.
Command syntax
Sessions come from each runtime’s own local session store, not from 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, and no runtime file is changed.

​
Supported runtimes

When a Codex thread has more than one rollout file, beacon handoff lists it once, under its newest file. Cline can hold the same task both as a CLI session and in its older task history; the CLI session is the copy that is listed. Cline kanban cards are not sessions and are not listed.

​
beacon handoff list

Lists resumable sessions, newest first.
A store that cannot be read is reported as a warning (on stderr, or under warnings in JSON), and the sessions from the other runtimes are still listed.

​
beacon handoff export

Writes a handoff brief for one session: a Markdown summary of what it asked for, what it changed, and where it stopped, for another agent or person to continue from.
The session id can be a unique prefix of at least six characters. Pass --harness when two runtimes use the same id. A brief has these sections:
  • Source session: runtime, session id, title, directory, branch, last activity, session file, and activity counts.
  • Where it stood: the first request, the latest request, and the last agent message.
  • Files changed and Recent commands, with exit codes where the runtime reports them.
  • Recent activity: the last 30 steps (prompts, agent messages, commands, file changes, tool failures, MCP calls), each cut to 1,200 characters.
  • Before continuing: check the working tree, and confirm the task before changing anything.
A brief is a summary, not the full transcript. Every event goes through the same secret redaction and truncation as the runtime log before any of it is used. Agent reasoning and file reads are left out. A brief is at most 48 KiB; older steps are dropped first to stay under that. Content is placed in code fences longer than any run of backticks inside it, so quoted text can’t close its block and pass itself off as part of the brief. When a session is no longer in its runtime’s store (for example, a deleted transcript), export reads it from Beacon’s runtime log instead. This works for any runtime Beacon captured, but the log keeps less of each step, and the brief says so. Briefs are written to ~/.beacon/endpoint/handoffs. The directory is 0700 and each file is 0600, because a brief carries prompt text and command output. An existing brief is never overwritten.

​
beacon handoff resume

Picks a session up again, in its own runtime or another one.
There are two ways to resume:
  • Reopen natively. Beacon reopens the session with its full context when all of these hold: it continues in the same runtime, that runtime’s CLI can load this kind of session, and the session file is still on this machine.
  • Start a new session from a brief. Otherwise, or with --agent naming another runtime or with --new, Beacon writes a brief (see export) and starts a new session. The first message of that session points at the brief: The prompt names the brief by its path and asks the agent to read it, then confirm the task before changing anything. The brief is never inlined into the command line, because a command line is visible to every local user through the process table. The prompt ends with a handoff marker (see below).
Claude Code and Cline subagent sessions, and Cline’s older task history, can’t be reopened by their CLIs, so they always continue from a brief. A session known only from Beacon’s runtime log also continues from a brief, and it needs --agent if its own runtime isn’t one of the four above. Cline approves every tool call by default. Beacon always passes --auto-approve false, so a session Beacon starts never gets auto-approval on Beacon’s say-so. You can still turn it on inside the Cline TUI. The runtime runs in this terminal, in the session’s recorded directory. If that directory no longer exists, Beacon stops rather than starting somewhere else; pass --cwd to choose a directory. Beacon prints the plan and asks Continue? [Y/n] before launching. Without a terminal, it launches only with --yes. beacon handoff resume exits with the runtime’s own exit code.

​
Linking a new session to the one it continues

A session started from a brief has a new session id. So that the two stay connected in the telemetry, the first prompt of the new session ends with a handoff marker:
When Beacon’s hook adapter records a prompt carrying this marker, it writes a second event, session.handoff, next to the usual prompt.submitted:
The link event keeps the new session’s id, workspace and harness, and leaves the prompt text to the prompt event. Rules can match on e.handoff.source_harness and e.handoff.source_session_id. Two paths record the link:
  • Live hooks. The prompt hook for Claude Code and the Cline and OpenCode plugins record it as the prompt is sent (harness.collection_method: hook).
  • Session-store sync. beacon endpoint claude sync, codex sync, opencode sync and cline sync record it when they read the prompt back from the runtime’s store (harness.collection_method: poll).
Codex CLI prompts reach Beacon over OTLP and through beacon endpoint codex sync, not a prompt hook, so a session continued in Codex is linked by the sync. For the other three runtimes, a sync can record the same link a hook already did; the two carry different collection_method values, as every other event those runtimes report through both paths does. A sync’s link has a deterministic event.id, so syncing again never duplicates it. The marker is a claim made in prompt text, not a verified identity: anyone can type it. fidelity: observed records that the marker was seen, not that beacon handoff resume wrote it. A native resume keeps the session’s own id, so it needs no link.