by:, or the codename in a <date>-<codename>-<project> slug, or the session’s relay title), and --lane names one explicitly. With no codenames anywhere, a project is one lane and keeps one open handoff, as it always did.
The trap, first
Since 0.16.0 the output says what it did:lane: <name> (from <where>), then archived: <slug> for each handoff it archived (or archived: nothing), then any handoffs it left open in other lanes. Read that line, and base handoff unarchive <slug> undoes a mistake.
Why it works this way. The archive flips the earlier open (or deferred) handoff for the same project and lane to archived, in every tier, before registering the new one, and it leaves forks alone. One open thread per lane is what “resume this” rests on. Before 0.16.0 the sweep covered the whole project, so several sessions working one project archived each other’s handoffs; lanes stop that.
Creating a handoff
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:
--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
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
show takes what you remember of it and prints its path:
base handoff show takes a letter from the last session start (A to J), a slug, a project name or a few words. Several matches are listed and none is picked (exit 2); no match exits 1. Each session reads its own letters, so another session’s start does not change what yours point at.
Dismissing one
base handoff unarchive docs-pickup or base fork unarchive docs-site sets it back to open, in the tier that holds it.
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 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. They do not bypass the budget. Since 0.16.0 session start fits everything it prints to[budget] session_start_bytes, in a fixed layout: a header line with every count, short instructions, DUE NOW, then HANDOFFS, newest first, one per project with the older ones counted, lettered A to J; then the newest 3 forks, projects, tasks and milestones. What is due always sits on the first screen. The header names the file that holds the full, untrimmed output, and base handoff list and base fork list show everything.
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, by its letter or a few words, and the agent runsbase handoff show and reads the document it prints.
Work that goes quiet
With deferral turned on ([defer] enabled = true, off by default), a handoff or fork nobody has touched for a set number of days stops showing at session start. It is not archived: base handoff deferred and base fork deferred list it, and base handoff show or base fork show brings it back. Opening its document counts as touching it. See deferred work.
The global tier
base handoff and base fork both carry -g / --global, and it goes on the command itself, before the verb:
-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.