Handoff

Handoff gives omp a clean, task-oriented context when a conversation has accumulated too much history. It summarizes the work completed so far, the decisions that matter, and what should happen next, then compacts that summary into the current session.

Run it when you want the next turn to continue from a deliberate checkpoint:

/handoff

While omp prepares the handoff, the status line shows Generating handoff… (esc to cancel). On success, the conversation is rebuilt around a handed-off divider and omp reports Context handed off and compacted in place.

Despite the name, /handoff does not create, fork, or switch to another session. Your session ID, name, branch, and saved session stay the same.

Handoff or compact?Copy Anchor Link

Both commands reduce the model's active context in place and retain a recent tail of the conversation. Choose based on what you want the replacement context to emphasize.

Use /handoff before changing work phases, returning after a long pause, or preserving a precise implementation/debugging checkpoint. Use /compact when the priority is simply freeing context. If you actually want a separate session, use the session controls described in Sessions.

Focus the continuationCopy Anchor Link

Add plain-language focus instructions after the command:

/handoff Focus on the migration plan, decisions already made, and callers that still need updating.

The focus changes what the brief emphasizes; it does not become a new user task and does not create a new session. Without a focus, omp chooses the important continuation details from the conversation.

Good focus instructions name the work that must survive the reduction:

/handoff Preserve the test failure, hypotheses ruled out, and the next two debugging steps.

/handoff Emphasize the approved API shape and unresolved compatibility risk.

Wait for the current response to finish before running the command. If you need to stop that response, abort it first, then enter /handoff.

What changes on screenCopy Anchor Link

A successful handoff changes the context used for future model turns:

• Older context is replaced by the generated handoff brief.
• Recent messages remain verbatim. The retained amount is controlled by compaction.keepRecentTokens, which defaults to 20000.
• Todos and other live session UI are refreshed.
• The same session continues; there is no resume or load step.

By default, pre-handoff history is collapsed out of the live transcript and the recent tail appears after a divider similar to:

──────── handed-off · 180K→24K · ctrl+o ────────

Press Ctrl+O to expand the divider and read the generated brief. Set display.collapseCompacted: false if you prefer to keep the full saved transcript inline around compaction dividers. Collapsing affects the display, not the persisted session history.

Your next prompt can immediately continue the work:

Continue with the first remaining migration caller.

Cancel or recover from a failureCopy Anchor Link

Press Esc while Generating handoff… is visible to cancel. omp shows Handoff cancelled, leaves the current context unmodified, and keeps you in the same session.

Other preconditions and errors are also non-destructive:

An empty generated brief is treated as a failure, not as a cancellation. omp automatically retries transient provider failures, but if the final attempt fails it displays the real error and does not commit a partial handoff.

Automatic handoffCopy Anchor Link

Manual /handoff always requests the handoff workflow; it does not depend on automatic compaction being enabled or on compaction.methodOrder.

For automatic use, enable compaction and put handoff early in the ordered fallback list. The default order is:

remote → snapcompact → handoff → shake → soft

That means another available method may run before handoff. If automatic handoff cannot run or fails, omp tries the next configured method. When the input has already overflowed the model's context, omp normally skips starting a new handoff request because the same oversized input could not be summarized; an already-prepared speculative handoff may still be applied.

Open /settings and use Context → Compaction, or add a global or project override to config.yml:

compaction:
  enabled: true
  methodOrder: [handoff, remote, snapcompact, shake, soft]
  handoffSaveToDisk: true

handoffSaveToDisk adds a timestamped handoff-*.md file to the persisted session's artifact directory only for automatic handoffs. Manual /handoff stores the result as the session's compaction summary but does not write the extra Markdown file.

Relevant settingsCopy Anchor Link

See Settings for configuration locations, scopes, and precedence.

RelatedCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.