The Other Half of a Handoff

Until recently, handing work from one Claude Code session to the next was a copy-paste job. At the end of a session, I’d paste in the same instruction:

Save the status of this entire session to a handoff doc. Put it in ~/.handoffs. The doc should include a frontmatter flag for the previous session (this one), as well as an *empty frontmatter flag* that will be populated by the session that picks the handoff up.

That instruction handles the writing half reasonably well. The next session gets a doc with what was done, what’s still open, and what comes next, along with an empty field to mark it as taken. The other half, picking a handoff back up, was still entirely manual. Nothing stopped two sessions from picking up the same doc. By the time I had four handoffs sitting in ~/.handoffs, that field was called next_session in three of them and picked_up_by_session in the fourth.

Two Commands#

I turned the instruction into a small Claude Code plugin with a skill for each direction. /handoff:save writes the doc, and /handoff:load picks one up. /handoff on its own works out which one you meant: in a brand-new session it loads, and in a session that has already done some work it saves.¹

/handoff:save also writes the same frontmatter keys every time, including the empty one the next session fills in, so the loading side can actually rely on them.

Picking One Up#

/handoff:load takes optional hints, like a project or a topic:

/handoff:load billing migration

Before the model reads a single instruction, a small script lists the newest handoffs that no session has picked up yet, and marks the ones that belong to the repo the session is running in. The model matches the hints against that list. If one handoff clearly fits, it picks that one. If a few could, it asks, with a multiple-choice question that previews each candidate, so I can look at a handoff before I commit to it.

Loading a session is the half of this workflow that hadn’t been previously codified; I would typically have to find the exact handoff I wanted and explicitly paste it in (the path to the file; not the full contents). The script writes the new session’s ID into the empty field under a file lock, and only if the field is still empty, so two sessions can’t both claim the same handoff by accident. Taking over one that’s already claimed needs my OK. That matters more when you’re running several sessions at once (in worktrees, say). I raced two claims against each other twenty times while testing it, and each round had exactly one winner.

A handoff is a snapshot, so the loading session checks it against reality before doing anything: the branch, the working tree, and whether the PRs it mentions have merged since. Then it gives a short brief, and either starts on the task in the hints or waits for one.

Rules Survive the Chain#

There’s a quieter failure once handoffs start chaining. The rules I give a session, like asking before a merge or staying out of a particular repo, live in its handoff. When the next session saves its own handoff, nothing forced those rules to come along, so they could drop out after one hop. Each saved doc now records which handoff its session started from, and carries forward any of that handoff’s rules that still apply.