Skip to main content
A handoff is one continuity thread per project: the answer to “where did I leave this”. A fork is a build specification for side-work you want to keep visible without acting on now. The difference that matters: creating a handoff archives the project’s previous open handoff. Creating a fork archives nothing. One resume point per project, as many forks as you like.

​
The trap, first

Do not file side-work as a second handoff. handoff create archives the prior open handoff for that project without asking, so a second handoff written to capture a side-quest silently replaces your real resume point with the side-quest.If you want to keep both, the second one is a fork.
This is worth knowing before anything else on this page, because the failure is quiet. Nothing errors, nothing warns, and you find out next session when the thing that resurfaces is not the thing you were working on. Why it works this way. The archive is a SPARQL update that flips any open handoff for the same project to archived before inserting the new one, and it deliberately excludes forks from that sweep. One open continuity thread per project is the invariant the whole resume mechanism rests on: if there were two, “resume this project” would have no answer.

​
Creating a handoff

Why it works. Registering is what makes a handoff resurface. The document itself is inert: nothing scans your filesystem for markdown, and the graph node created by handoff create is the only thing session start reads. The gotcha. Writing the file is half the job, and it is the half that looks finished. Some flows print their own confirmation box after writing the document, which reads like completion. Always check:
Exactly one open handoff for the project, pointing at your document path. If it is not there, it does not exist as far as base is concerned. Next rung. --slug defaults to the document’s file name without its extension, which is the doc==slug protocol: keep the filename and the slug identical and the slug in base handoff list is enough to find the document, with no second lookup. Pass --slug only when you deliberately want them to differ.

​
Creating a fork

Why it works. Forks are additive by design. Creating one touches neither the project’s handoff nor any sibling fork, so several can be open at once and each is picked up by name. Re-running fork create on the same slug re-points that fork at the document rather than creating a duplicate, which makes it safe to run again after you have edited the spec. The gotcha. A fork document should describe what to build, not what happened. It is read later by someone deciding whether to start, and a retrospective is the wrong shape for that.

​
Which one you want

​
Seeing what is open

Both read across the global tier and the workspace together, and show which tier each entry lives in. The gotcha. There is no handoff show or fork show. To read a document’s content, open the path that list prints.

​
Dismissing one

Snooze hides it for a number of days. Archive stops it resurfacing for good. The gotcha. Both arguments to snooze are positional: the slug, then the number of days. base handoff snooze docs-pickup --days 7 is not the syntax.

​
Why it keeps coming back

Handoffs, forks and reminders surface at the start of every session until you act on them. They are the three categories exempt from the mechanism that keeps everything else quiet. Why it works. Most injected content is hashed, and output that has not changed since last time is skipped, so silence is the normal steady state. Handoffs, forks and reminders bypass that check entirely, and they also bypass the character budget that trims other session-start content. Established from source at 4866996, the commit the shipped 0.13.2 binary was built from. That is deliberate: an open loop that stops reminding you is an open loop you have lost. Acting on it, snoozing it or archiving it are the three ways it goes quiet, and all three are decisions rather than side effects.

​
Resuming

Mostly you do nothing. The open handoff arrives at session start, and you pick up from it. With several open across projects, name the one you mean and the agent will find and read the matching document from base handoff list or base fork list.

​
The global tier

base handoff and base fork both carry -g / --global, and it goes on the command itself, before the verb:
Use it for work that genuinely is not scoped to one project. Outside a registered workspace, base refuses the write rather than filing it globally by default, and tells you to either scaffold or pass -g deliberately.

​
Next

Multiple sessions

Handing work between sessions running at the same time.

Sessions reference

Every handoff, fork and relay command, with its flags.