Relace Compact for OMP and pi-agent ⚡️

Route conversation compaction through Relace Compact instead of spending another model request on summarization.

• 🚀 OMP: integrates with OMP's native context-full compaction path.
• 🧭 pi-agent: routes every native compact through Relace and adds percentage/token thresholds plus idle timers.
• 🔐 Safe configuration: API keys can come from RELACE_API_KEY and project-local settings are only used when trusted.
• 🛠️ One command: inspect, enable, disable, reset, or manually compact with /compact-relace.

How it works

1. The host prepares the messages that are eligible for compaction.
2. This extension converts them to Relace's message format and sends them to the configured endpoint.
3. Relace returns a shorter message history.
4. The extension returns that history to the host and persists enough metadata for resumed sessions.
5. New turns are appended after the Relace replacement history.

The extension never implements a second summarizer. It is a transport adapter from OMP/pi-agent to Relace.

Install

pi-agent — listed on the Pi package marketplace (npm-backed):

pi install npm:relace-compact-pi

OMP — install the npm package:

omp plugin install npm:relace-compact-pi

Version 0.2.2 fixes installation in OMP versions that validate extensions before initializing settings. Registration no longer accesses the settings proxy's methods; OMP settings are read when runtime handlers execute.

OMP 18.4 uses registry-backed settings instead of Settings.get(). The extension reads the effective configured layers through rawValue() at runtime, including project and runtime overrides. Unset native settings use OMP's defaults: idle compaction disabled, a 300-second delay when enabled, and remote first in the compaction order. Move soft first to enable Relace routing.

Update

pi update npm:relace-compact-pi                 # pi-agent: update this package
omp plugin install npm:relace-compact-pi@latest # OMP: pull the latest npm release

The plugin is on the Pi package marketplace but not in an OMP marketplace, so OMP updates pull from npm. omp update --plugins and omp plugin upgrade only cover OMP-marketplace plugins and won't detect a new npm release of this package.

For local development, link a checkout instead of installing from npm:

git clone https://github.com/thejorgg/relace-compact-pi relace-compact-pi
cd relace-compact-pi
omp plugin link .
# or
pi install .

Use the published package for normal installs; link a checkout only while developing the plugin.

Configure target and thresholds through the command

You can just run:

/compact-relace target [value] /compact-relace threshold [value]

inside pi or omp

Configure OMP (soft compaction only) 🧩

Relace replaces OMP's summarizing compaction path. In OMP 18, that path is named Soft compaction; older OMP versions called it Context-full. Other methods such as remote, handoff, snapcompact, and shake are not Relace-routed.

1. Set the Compaction Method Order and Idle Settings

In OMP, open Settings → Context → Compaction Method Order and move Soft compaction to the top. Equivalently, edit your global configuration (~/.omp/agent/config.yml) or project-local configuration (.omp/config.yml) under the compaction: block:

compaction:
  methodOrder:
    - soft
    - remote
  idleEnabled: true
  idleTimeoutSeconds: 1800

[!IMPORTANT] The first method must be soft for Relace routing to be active in OMP 18. /compact-relace status reports the current first method and the exact setting to change.

For the idle model overrides, use the following:

omp plugin config set relace-compact-pi relace.idleModelOverrides "{\"openai/gpt*\":1800,\"openai-codex/gpt*\":1800,\"anthropic/claude*\":300}"
omp plugin config set relace-compact-pi relace.idleMode beforeNextTurn

Alternatively, use the JSON:

Linux / macOS: $HOME/.omp/plugins/omp-plugins.lock.json

Windows (⚠️ unconfirmed): %appdata%/.omp/plugins/omp-plugins.lock.json

{
  "plugins": {
    "relace-compact-pi": {
      "version": "0.1.0",
      "enabledFeatures": null,
      "enabled": true
    }
  },
  "settings": {
    "relace-compact-pi": {
      "relace.idleModelOverrides": "{\"openai/gpt*\":1800,\"openai-codex/gpt*\":1800,\"anthropic/claude*\":300}"
    }
  }
}

2. Configure the Relace API Key

The only plugin-specific setting you need to configure is your API key.

Option A: Environment variable (Recommended)

export RELACE_API_KEY="YOUR_RELACE_API_KEY"

Option B: Using the OMP CLI

omp plugin config relace-compact-pi set relace.apiKey "YOUR_RELACE_API_KEY"

Configure pi-agent 🤖

Pi-agent reads global settings from $HOME/.pi/agent/settings.json (or $PI_CODING_AGENT_DIR/settings.json) and trusted project settings from .pi/settings.json.

{
  "relace": {
    "enabled": true,
    "apiKey": "",
    "endpoint": "https://models.relace.ai/v1/code/compact",
    "targetPercent": 33,
    "idleTimeoutSeconds": 600,
    "idleMode": "beforeNextTurn",
    "idleModelOverrides": "{\"openai/gpt*\":1800,\"anthropic/claude*\":300}",
    "pi": {
      "thresholdType": "percentage",
      "threshold": 66
    }
  }
}

Settings

| Setting | Default | Description | | --- | ---: | --- | | relace.enabled | true | Enable or disable Relace routing. | | relace.apiKey | empty | Relace API key. RELACE_API_KEY takes precedence. | | relace.endpoint | production endpoint | Relace Compact endpoint. | | relace.targetPercent | 33 | Target percentage of the active model context. | | relace.idleTimeoutSeconds | 600 | Global idle compaction delay; 0 disables it. | | relace.idleMode | beforeNextTurn | When idle compaction runs. beforeNextTurn waits until you actually submit your next message and compacts right before that turn starts; backgroundAuto compacts in the background as soon as the idle timer fires. | | relace.idleModelOverrides | {} | JSON string mapping model globs to idle seconds. | | relace.pi.thresholdType | percentage | Pi threshold interpretation: percentage or tokens. | | relace.pi.threshold | 66 | Pi compaction threshold. |

Model override examples:

"relace.idleModelOverrides": "{\"openai/gpt*\":1800,\"openai-codex/gpt*\":1800,\"anthropic/claude*\":300}"

A pattern containing / matches provider/model; a pattern without / matches the model ID. * is the wildcard.

Idle compaction timing

With the default relace.idleMode: "beforeNextTurn", the idle timer only marks the session as due for compaction. The Relace compaction then runs right before your next message is processed — so if you stop to read the output and never send another message, no compaction tokens are spent. It still respects the idle timeout: if you keep working without pausing long enough, nothing is marked due and no compaction is triggered.

Set "idleMode": "backgroundAuto" to restore the old behavior and compact in the background as soon as the idle timer fires.

Commands 💬

/compact-relace
/compact-relace compact
/compact-relace status
/compact-relace enable
/compact-relace disable
/compact-relace reset
/compact-relace target [value]
/compact-relace threshold [value]

• Bare /compact-relace prints usage.
• compact starts a Relace compaction.
• status reports host, route, target, context, idle timer, and session count.
• disable persists relace.enabled: false.
• enable persists relace.enabled: true.
• reset clears the current session's replacement history and counter.
• target [value] views the current target percentage, or sets it (e.g. 25% or 25).
• threshold [value] views the current threshold, or sets it (e.g. 66%, 5000, or 5000 tokens).

API key and privacy 🔒

export RELACE_API_KEY="your-relace-key"

The extension sends only the messages selected for compaction, the target token count, and the active model identifier to the configured Relace endpoint. Do not configure an untrusted endpoint with a credential you do not intend to share.

Development

bun install
bun run check
bun run lint
bun run fmt