Handoff

/handoff [focus] closes the current turn by generating a short document that captures state, open threads, and next steps, then opens a brand-new session with that document injected as its first piece of context. The old session keeps its transcript untouched; the new one starts clean except for the wrap-up.

When to reach for it

Use /handoff when the session is done with this chunk of work but the work itself isn’t done:

End of a debugging or implementation push, before you walk away.
Switching context — same project, different feature — and you want the next session to start without 200 turns of unrelated history.
Before a long pause (overnight, end of week) where you’ll want a quick refresher when you come back.
Handing the JSONL to a teammate. They resume into the new session and see the wrap-up first, not the raw transcript.

If you only need to shrink the active context to fit the next turn, use /compact instead. Compaction stays in the same session and summarises in place; handoff ends the session and creates a successor.

The optional [focus] argument biases the document toward what you care about, e.g. /handoff Focus on the migration plan and which callers still need updating. Without it, the generator picks its own structure.

/handoff refuses with Nothing to hand off (no messages yet) if the current branch has fewer than two messages — too little to summarise usefully.

What gets written

The generator runs as a side-channel model call at the session’s current thinking level with tools disabled, so expect 10–20 seconds while a loader sits in the status line: Generating handoff… (esc to cancel). The output is free-form markdown — typically what was being worked on, the current state of the code, what remains, and any decisions or constraints worth carrying forward.

The text is wrapped and appended to the new session as a custom_message entry of type handoff:

<handoff-context>
...handoff text...
</handoff-context>
 
The above is a handoff document from a previous session. Use this context to continue the work seamlessly.

Because it’s a custom_message, the entry shows up in the TUI when you rebuild the chat and participates in the LLM context on every subsequent turn of the new session.

The new session

When generation completes, /handoff flushes the old session to disk, creates a fresh session file, and points its parentSession header at the old session file. That lineage marker is the same one /fork writes, so the two sessions show up as connected when you walk the tree.

After the swap you’ll see New session started with handoff context in chat, and /context will show the wrap-up entry as part of the message bucket. The previous session is not modified — the wrap-up is never appended to the old transcript, only to the new one.

Cancelling and failures

Press Esc while the loader is visible to abort the request. UI reports Handoff cancelled and you stay in the original session with no changes on disk. The same message is shown if the model returns no text. Any other error — provider failure, network drop — surfaces as Handoff failed: <message> and again leaves the original session intact.

Reading the handoff back

The next session resumes the way any session does: omp -c from the same directory, or omp --resume <id-prefix> from anywhere. Because the handoff is the first real entry, the agent reads it on turn one and the human reads it at the top of the rebuilt chat. There’s no separate “load handoff” step.

/fork from the new session clones the lineage forward, carrying the handoff entry with it. /tree walks back into the new session’s own history; to step into the parent session, resume it by id from ~/.omp/agent/sessions/<cwd-hash>/.

Auto-triggered handoffs (the ones the compaction subsystem fires for you) can also drop a timestamped handoff-*.md under the session’s artifacts directory when compaction.handoffSaveToDisk is set. Manual /handoff skips that file — the JSONL entry is the canonical copy.

Sessions — resume, branch, fork, and the rest of the session toolkit.
Compaction — when to compact in place instead of handing off.
Plan mode — pair a plan with a handoff to ship the spec into the next session.\n