> ## Documentation Index > Fetch the complete documentation index at: https://docs.basemode.ai/llms.txt > Use this file to discover all available pages before exploring further. # Handoffs and forks > Ending a session so the next one resumes where you stopped, parking side-work without derailing what you are doing, and which of the two you actually want. 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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} base handoff create --project basemode --doc "/home/you/basemode/.base/handoffs/2026-08-25-1430-otter-basemode.md" ``` **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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} base handoff list ``` 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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} base fork create --project basemode --doc "/home/you/basemode/.base/forks/docs-site.md" ``` **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 | You are about to stop and want to... | Use | | ---------------------------------------------------------- | --------- | | Record where the main thread of this project stands | `handoff` | | Capture a feature you agreed to build but have not started | `fork` | | Note a second, unrelated piece of work in the same project | `fork` | | Replace an out-of-date resume point | `handoff` | ## Seeing what is open ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} base handoff list base fork list ``` 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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} base handoff snooze docs-pickup 7 base handoff archive docs-pickup base fork snooze docs-site 14 base fork archive docs-site ``` 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} base handoff -g list base fork -g create --project basemode --doc "/home/you/notes/spec.md" ``` 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 Handing work between sessions running at the same time. Every handoff, fork and relay command, with its flags.