opencode-context-compress

Manual-first context compression. You own the when.

OpenCode plugin for explicit, user-triggered context compression. It helps the model fold completed conversation phases into durable technical summaries only when you ask for it.

Core Behavior

• No autonomous context management loops.
• No automatic nudges or per-turn injections.
• Compression runs only when you trigger /compress manage.
• During /compress manage, the agent can use compress_map and compress (subject to permissions).
• After that management turn completes, its trigger, tool calls, tool outputs, map snapshots, and assistant chatter are hidden from future model prompts.

Commands

• /compress or /compress help: show command help.
• /compress manage: send a lean context-management reminder to the active agent.
• /compress context: show token usage breakdown for the current session.
• /compress stats: show session and all-time compression totals.

/compress manage is the only command that intentionally creates a model-visible turn.

Agentic Workflow

When /compress manage runs, the plugin opens a single model-visible management turn with a short reminder. Inside that turn the agent can:

1. Call compress_map to fetch the current <compress-context-map> snapshot.
2. Call compress with one range at a time to replace completed phases with topical blocks.
3. Read the refreshed map returned by compress and continue iterating in the same turn if needed.

The manual boundary stays absolute: outside a user-triggered /compress manage turn, the plugin does not prompt for compression or open any background workflow.

While the management turn is running, the agent can see its own maps and tool results. On later turns, the model-visible context contains only compressed [bN] blocks, normal conversation between compression runs, and the active tail. The cleanup leaves no marker or placeholder behind.

Context Map

compress_map and compress both use the same structured map format:

<compress-context-map>
[1] user: "Let's implement JWT auth"
[2-4] assistant: 5 tool calls - auth exploration (~1,240 tokens)
[b0] [compressed] "Prior database migration debugging" (~420 tokens)
[5] user: "Looks good, now add tests"
[6-8] assistant: 4 tool calls - test implementation (~2,180 tokens)
---
Total: 8 messages + 1 block | ~6,500 tokens
</compress-context-map>

The agent decides what counts as the active tail. Older completed work should be compressed more tersely than the most recent completed phase. Block labels follow where their anchors appear in the conversation stream, so re-compressing one block does not renumber unrelated blocks.

Installation

npm (Recommended)

npm install @skybluejacket/opencode-context-compress

Then add it to your config:

| Platform | Global | Project-level | | --- | --- | --- | | OpenCode | ~/.config/opencode/opencode.jsonc | .opencode/opencode.jsonc | | OpenCodeOrchestra | ~/.config/oco/oco.jsonc | oco.jsonc or .oco/oco.jsonc |

{
    "plugin": ["@skybluejacket/opencode-context-compress"]
}

From Source

Clone the repo, build, and reference the compiled entry file directly:

git clone https://github.com/AidenGeunGeun/opencode-context-compress.git
cd opencode-context-compress
npm install
npm run build

{
    "plugin": ["file:///absolute/path/to/opencode-context-compress/dist/index.js"]
}

Configuration

Config files are loaded and merged in this order:

1. ~/.config/opencode/compress.jsonc (or compress.json)
2. $OPENCODE_CONFIG_DIR/compress.jsonc (or compress.json)
3. <project>/.opencode/compress.jsonc (or compress.json)

If no global config exists, the plugin creates ~/.config/opencode/compress.jsonc with:

{
    "$schema": "compress.schema.json"
}

Default runtime config:

{
    "enabled": true,
    "debug": false,
    "notification": "detailed",
    "notificationType": "chat",
    "commands": {
        "enabled": true,
        "protectedTools": ["task", "todowrite", "todoread", "compress", "compress_map", "batch", "plan_enter", "plan_exit"]
    },
    "turnProtection": {
        "enabled": false,
        "turns": 4
    },
    "protectedFilePatterns": [],
    "tools": {
        "settings": {
            "protectedTools": ["task", "todowrite", "todoread", "compress", "compress_map", "batch", "plan_enter", "plan_exit"]
        },
        "compress": {
            "permission": "allow",
            "showCompression": false
        },
        "compress_map": {
            "permission": "allow"
        }
    }
}

Persistence

Session state is stored at:

• ~/.local/share/opencode/storage/plugin/compress/<sessionId>.json

Stored fields include:

• compressed tool IDs
• compressed message IDs
• compression summaries
• completed management-turn cleanup markers
• per-session compression stats

The raw conversation history still exists in OpenCode storage, but completed /compress manage machinery is suppressed from future model prompts. Restarting the session reloads the saved cleanup markers, so old management turns do not reappear in the model-visible stream.

Development

npm install
npm run generate:prompts
npx tsc --noEmit
npm test

Prompt utility docs are in scripts/README.md.

License

MIT