Context Plus

Context Plus (processmission/pi-context-plus) is a context-compaction router for both Pi and Oh My Pi (OMP). On native-capable OMP models it delegates to the host's Codex-compatible Remote Compaction V2. Everywhere else it supplies a portable CONTEXT CHECKPOINT text handoff.

Features

• Supports both Pi extensions and OMP plugins from the same package.
• Automatically delegates OMP's OpenAI-compatible models to provider-native Remote Compaction V2/V1.
• Computes upstream Pi's trigger from the active model's current context window (90% by default), including after model switches.
• Produces portable handoff summaries with Codex's context-checkpoint structure when native replay is unavailable.
• Carries the previous text summary into recursive fallback compactions.
• Builds an exact-literal continuity checklist for identifiers, paths, dates, limits, and other load-bearing facts.
• Repairs summaries that lose current facts without reviving explicitly superseded details.
• Uses the fast pi/smol model role and low reasoning effort for text checkpoints by default.
• Caps fallback-summary input so compaction stays bounded as sessions grow.
• Restores artifact-spilled content before summarizing when the host exposes artifact reads.
• Falls back to native compaction if model resolution, authentication, generation, or repair fails.

Pi or OMP still owns triggering, history installation, persistence, and retained-message policy. With the default backend: "auto", Context Plus returns no custom compaction when the host advertises provider-native replay, allowing OMP to store the opaque compaction item. Otherwise it replaces only the text-summary step through session_before_compact. It never performs token-by-token background compression.

Compaction is automatic when the host's threshold is enabled. The recommended OMP settings below match Codex's 90% trigger and run only at safe pre-turn, mid-turn, or maintenance boundaries. Upstream Pi has no percentage setting, so Context Plus evaluates tokens > current contextWindow × piThresholdPercent at settled/model-switch boundaries and supplies the portable checkpoint fallback.

Install

Pi

pi install git:github.com/processmission/pi-context-plus
pi list

Restart Pi or run /reload after installation.

Installing the extension does not rewrite Pi's host settings. Pi enables automatic compaction by default; only the retained-message window needs optional host configuration:

// ~/.pi/agent/settings.json or <project-dir>/.pi/settings.json
{
  "compaction": {
    "enabled": true,
    "keepRecentTokens": 20000
  }
}

Pi's built-in trigger is based on fixed reserveTokens, but Context Plus overlays a model-relative policy. If the built-in threshold would fire below piThresholdPercent, the hook defers that threshold compaction; if it would fire later, Context Plus requests compaction after the agent settles. The threshold is recalculated from ctx.getContextUsage().contextWindow on every check, so switching between 128k, 272k, and 1M models does not require editing settings. Manual and overflow compactions are never deferred.

OMP

omp plugin install github:processmission/pi-context-plus
omp plugin list
omp plugin doctor

Restart OMP after installation. Installing the plugin does not rewrite OMP's host settings. OMP must use the context-full compaction strategy; shake, handoff, and snapcompact bypass the summary hook.

# ~/.omp/agent/config.yml
compaction:
  enabled: true
  strategy: context-full
  thresholdPercent: 90
  thresholdTokens: -1
  midTurnEnabled: true
  reserveTokens: 16384
  keepRecentTokens: 20000
  autoContinue: true
  remoteEnabled: true
  remoteStreamingV2Enabled: true
  v2RetainedMessageBudget: 64000
  idleEnabled: false

thresholdPercent: 90 matches Codex's normal automatic threshold, while thresholdTokens: -1 leaves the percentage in control. idleEnabled: false prevents OMP's separate idle threshold from compacting earlier. Remote V2 sends the native model-visible history plus compaction_trigger, stores the opaque result, and retains up to 64k tokens of real user messages. autoContinue controls whether OMP resumes after compaction; it does not trigger compaction.

For a local OMP checkout, ./install.sh installs dependencies, links the plugin, and applies the recommended compaction threshold. It backs up the existing OMP configuration before editing it.

The package contains both manifest entries:

• pi.extensions for Pi
• omp.extensions for OMP

Settings

Create config.json next to index.ts using config.example.json, or set the corresponding environment variables.

Setting	Environment variable	Default	Description
backend	PI_CONTEXT_PLUS_BACKEND	auto	auto delegates native-capable OMP models; host always delegates and disables Pi's percentage overlay; checkpoint always generates portable text.
piThresholdPercent	PI_CONTEXT_PLUS_PI_THRESHOLD_PERCENT	90	Upstream Pi trigger as a percentage of the active model's current context window; clamped to 1–99.
summaryModel	PI_CONTEXT_PLUS_SUMMARY_MODEL	pi/smol	Model role or provider/model used for text checkpoints.
summaryEffort	PI_CONTEXT_PLUS_SUMMARY_EFFORT	low	Reasoning effort: off, low, medium, high, or xhigh.
maxSummaryTokens	PI_CONTEXT_PLUS_MAX_SUMMARY_TOKENS	0.5 × reserveTokens	Summary output limit, clamped to 256–16384 tokens.
maxConversationTokens	PI_CONTEXT_PLUS_MAX_CONVERSATION_TOKENS	12000	Maximum serialized conversation input.
codexSummaryPrefix	PI_CONTEXT_PLUS_CODEX_SUMMARY_PREFIX	false	Prepend Codex's summary framing text.
resolveArtifacts	PI_CONTEXT_PLUS_RESOLVE_ARTIFACTS	true	Resolve artifact:// content before summarizing.
debug	PI_CONTEXT_PLUS_DEBUG	false	Show compaction progress and fallback notifications.

Environment variables override config.json. Setting summaryEffort to off also disables provider reasoning for the summary call. In auto mode, /compact <focus> uses the portable checkpoint path because provider-native compaction has no custom-focus channel; backend: "host" overrides that behavior.

Verify

Start the host with debug notifications, then run /compact or wait for automatic compaction:

PI_CONTEXT_PLUS_DEBUG=1 pi
# or
PI_CONTEXT_PLUS_DEBUG=1 omp

There are two successful outcomes:

• Native OMP route: debug reports delegating to host-native compaction; the saved entry has fromExtension: false and preserveData.openaiRemoteCompaction.version: "v2" (or a V1 replacement payload).
• Portable checkpoint route: debug reports compacting … followed by codex-style compaction done; the entry has fromExtension: true and details.strategy: "codex-context-checkpoint".

Use /compact remote in OMP for an explicit native-path smoke test. Do not print or publish replacementHistory: it contains provider-native opaque state.

Development

bun install
bun test
bunx tsc --noEmit

License

MIT — Copyright (c) 2026 Process Mission. See LICENSE.