Skip to content

WorkHandoff

All work

Case study 09 of 11

Handoff

A session moved between agents and machines

A plugin for the bb agent IDE that hands a thread to another coding agent or machine, or adopts a terminal session into bb, carrying a rendered transcript and the uncommitted work it talks about.

Role
Author and maintainer
Platform
bb plugin
Stack
TypeScriptReactZodVitest
Share

Context

No agent can load another agent's session file. Claude Code's session log means nothing to Codex, Codex's rollouts mean nothing to opencode, and a session is pinned to the machine whose disk it sits on.

Handoff starts from one idea, stated in its README: the portable thing isn't the session format. It's a rendered transcript plus the working state it talks about. It applies that idea in both directions. Hand off sends a bb thread to a new thread on any other agent installed in bb, on this machine or another enrolled one. Adopt brings a Claude Code, Codex, Gemini CLI, OpenCode or Pi session from the terminal into bb, in the same directory, with its history.

Role & approach

I built it as one plugin for bb, the agent IDE, in TypeScript, after starting with two that solved the same problem from opposite ends. A hand-off reads bb's own event log, which is the same whichever agent ran the thread, and renders it as one document: every message, tool call with its arguments and result, command output, reasoning summary, plan and file change. It is a transcript, not a summary. Long sessions keep the opening request and the recent end and drop the oldest middle first. Preview shows the document byte for byte before anything starts.

Adopting works the other way, with one small adapter per agent that reads that agent's own session store and emits a shared transcript model. Adding an agent means writing one adapter. The new thread starts in the session's own directory, so the files are where they were left, and the transcript goes to the agent as context rather than into the visible timeline.

A machine hop is the one case where a transcript alone would mislead: the files it discusses are on a disk the next agent can't see. So a hand-off to another machine also reads the git state, writes everything uncommitted as a patch on the target machine, and tells the next agent how to apply it. Lookups on another machine are bounded at three seconds, so a machine that is asleep can't stall bb. The commit that shipped this records the check: a dirty repository handed off between two Macs arrived with its uncommitted work applied.

The README is plain about the limits. Continuation is transcript-based, not a native resume: the new thread is a fresh session seeded with the conversation. Untracked build output, ignored files and anything outside the repository stay behind, and agents that don't keep full transcripts on disk can't be adopted.

Outcome

Handoff is open source under the MIT license and installs from bb's community marketplace. Every bb thread gets a Hand off panel and a "Hand off from here" action on each message, which leaves out a false start and everything after it. The new-thread screen can adopt an outside session by id or by its resume command, and a bb handoff command does the same from a terminal, including an export of the document for use outside bb.

Since it went public, other developers have contributed through pull requests, including adoption of Pi sessions.

Available for new engagements Remote, worldwide

Have something like this to build?