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

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 (context-full only) 🧩

OMP's automatic handoff, snapcompact, shake, and off strategies are not replaced. Select Context-full in OMP's compaction settings.

1. Set the Compaction Strategy and Idle Settings

Edit your global configuration (~/.omp/agent/config.yml) or your project-local configuration (.omp/config.yml) under the compaction: block. The plugin automatically respects your native OMP idle settings (idleEnabled and idleTimeoutSeconds):

compaction:
  strategy: context-full
  idleEnabled: true
  idleTimeoutSeconds: 1800

[!IMPORTANT] Compaction Strategy must be context-full for Relace routing to be active in OMP. The command /compact-relace status will show a notice when OMP is not set to context-full.

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