Compaction

Long sessions eventually contain more text than a model can consider at once. omp keeps the work moving by compacting older context while preserving the recent conversation. You normally do not need to do anything: automatic compaction is enabled by default.

Start with:

/context

This shows how much of the active model's context window is in use and how much room remains before automatic maintenance. Keep working normally unless omp has lost an important detail, the context is dominated by bulky output, or you want to choose what survives.

What automatic compaction doesCopy Anchor Link

As the context approaches the active model's limit, omp first removes stale file reads, empty searches, and other bulky results that are safe to elide. It then tries the configured maintenance methods in order. The default order is:

1. provider-native server compaction, when the active route supports it;
2. snapcompact, which archives older history into dense images for a vision-capable model;
3. a structured handoff summary;
4. shake, which removes recoverable command, search, and file-output bulk without a summarization request;
5. soft compaction, which summarizes older history with a model.

An unavailable or failed method advances to the next one. The default order therefore works across text-only and vision-capable models without model-specific configuration.

Whichever method succeeds, the active model keeps the recent tail of the conversation and receives a compact replacement for older context. Exact wording from the older turns is no longer in the model's live window, but normal compaction does not delete the original session record.

Automatic maintenance can happen:

• after a successful response crosses the threshold;
• between model requests during a long turn involving many commands or file reads;
• after a context-overflow or incomplete-output response, followed by a retry;
• while idle, but only when idle compaction is explicitly enabled.

By default, omp can prepare a summary shortly before the threshold so the visible pause is smaller. After threshold maintenance it continues the work automatically. Overflow and incomplete-output recovery retry the interrupted work instead.

What you seeCopy Anchor Link

The TUI shows a status such as Auto server compaction…, Auto-snapcompact…, Auto-handoff…, or Auto-shake…. Press Esc to cancel it. Text entered while compaction is running waits until maintenance finishes.

After a summarizing method succeeds, the transcript is rebuilt around a slim divider such as soft-compacted, remote-compacted, or handed-off, usually with a token reduction such as 256K→20K. Pre-compaction history is collapsed by default. Press Ctrl+O to expand the summary at the divider.

Automatic shake instead reports Auto-shake completed and replaces eligible heavy regions with short placeholders. With compaction.autoContinue: true (the default), threshold-triggered maintenance continues without waiting for another prompt.

Choose a manual recovery pathCopy Anchor Link

Use the least destructive command that matches the problem:

/compact: the normal manual choiceCopy Anchor Link

Run /compact to compact now using the first usable configured manual method:

/compact

Add focus instructions when older context contains several threads and one matters most:

/compact Preserve the API decisions, unresolved test failure, and exact next steps. Treat benchmark experiments as disposable.

You can select a one-off method without changing settings:

Manual /compact works even when automatic compaction is disabled. If a response is currently running, the command aborts that response before compacting. During the operation the TUI shows Compacting context… (esc to cancel); after success, the divider and reduced context usage confirm the result.

/handoff: preserve structured project stateCopy Anchor Link

Use /handoff when a generic conversation summary is too loose—for example, before moving from investigation to implementation or when a long task has many decisions and dependencies:

/handoff Focus on the accepted design, files already changed, verification still needed, and known risks.

Despite the name, the manual command currently compacts the current session in place. It does not open a successor session and does not save a Markdown handoff file by default. Wait for the current response to finish, or abort it, before running /handoff. See Handoff for the handoff document's contents and automatic handoff behavior.

/shake: remove bulk without summarizing the conversationCopy Anchor Link

/shake defaults to elide:

/shake

It replaces eligible command, search, and file-read output plus large fenced or XML-like blocks with short placeholders. In a persisted session, omp also saves the removed regions as a session artifact when possible; the placeholder includes an artifact://… recovery reference. If a removed result becomes important later, ask omp to recover the named region from that reference.

The targeted variants are more destructive:

A result such as Nothing to shake, No images found, or No thinking blocks found is a successful no-op, not an error.

ConfigurationCopy Anchor Link

The defaults are appropriate for most users. Change them through /settings, shell commands such as omp config set, or YAML in ~/.omp/agent/config.yml (an existing config.yaml is also honored). Project overrides can live in <project>/.omp/config.yml.

For example, this opts into idle maintenance while keeping the normal automatic behavior:

compaction:
  enabled: true
  idleEnabled: true
  idleThresholdTokens: 200000
  idleTimeoutSeconds: 300

Verify effective values from your shell:

omp config get compaction.enabled
omp config get compaction.methodOrder
omp config get compaction.thresholdPercent

Inside a session, run /context to verify the resulting threshold and available slack.

Settings referenceCopy Anchor Link

display.collapseCompacted is a related appearance setting. It defaults to true, hiding pre-compaction history from the live transcript while leaving the summary divider visible. Set it to false if you prefer the full stored transcript inline.

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link

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