Better Compact for OpenCode

Staged context pruning for OpenCode 1.17.13 and newer.

Install

opencode plugin better-compact --global

Restart OpenCode after installation.

The installer updates:

~/.config/opencode/opencode.json
~/.config/opencode/tui.json

JSONC files are preserved when present.

Commands

| Command | Action | | -------------------------- | ---------------------- | | /better-compact | Run Better Compact now | | /better-compact context | Show context usage | | /better-compact stats | Show the active plan | | /better-compact help | List commands | | /better-compact-settings | Open settings |

Configuration

Bypass Better Compact summaries defaults to on in the settings panel (compaction.bypassSummaries: true). Pruning still runs, but assistant previews and prefix summaries do not. Native automatic compaction remains under OpenCode's control, and its threshold measures the pruned request. A manual Better Compact run that cannot reach its target requests OpenCode's native compaction. Set the switch to off to enable Better Compact's summary stages.

Better Compact reads these files in order:

1. ~/.config/opencode/better-compact.jsonc or .json
2. $OPENCODE_CONFIG_DIR/better-compact.jsonc or .json
3. .opencode/better-compact.jsonc or .json

Project settings override global settings.

{
    "$schema": "https://raw.githubusercontent.com/AshishKumar4/better-compact/main/packages/opencode/better-compact.schema.json",
    "enabled": true,
    "compaction": {
        "automatic": true,
        "bypassSummaries": true,
        "preset": "light",
        "summaryEffort": "inherit",
    },
}

| Preset | Trigger | Target | Recent tool budget | | ---------- | ------: | -----: | -----------------: | | light | 85% | 35% | 40k tokens | | moderate | 75% | 25% | 30k tokens | | max | 60% | 15% | 12k tokens |

Changes made in /better-compact-settings apply to later runs without restarting OpenCode.

Upgrade

Use an explicit version to force a fresh OpenCode package cache entry:

opencode plugin [email protected] --global

If the plugin is missing after a failed or stale install, clear its cache and restart OpenCode:

rm -rf ~/.cache/opencode/packages/better-compact*

Uninstall

Remove better-compact from the plugin arrays in:

~/.config/opencode/opencode.json
~/.config/opencode/tui.json

Restart OpenCode.

Development

From the repository root:

pnpm install
pnpm --filter better-compact typecheck
pnpm --filter better-compact test
pnpm --filter better-compact build
pnpm --filter better-compact check:package

Use the checkout directly:

{
    "plugin": ["file:///path/to/better-compact/packages/opencode/index.ts"]
}

Add the TUI entry to ~/.config/opencode/tui.json:

{
    "plugin": ["file:///path/to/better-compact/packages/opencode/tui.tsx"]
}

Architecture

OpenCode runs Better Compact through two bundled entrypoints:

dist/index.js   server hooks and pruning runtime
dist/tui.js     commands, settings, reports, progress UI

The server applies a virtual plan to each outgoing request. OpenCode session history remains unchanged.

The pruning order is:

1. Remove loaded skill text.
2. Supersede repeated reads and remove stale failed-tool inputs.
3. Replace old tool calls and results with action stubs.
4. Remove old reasoning if more space is needed.
5. Remove remaining old tool traffic if more space is needed.
6. Collapse selected assistant runs and summarize them.
7. Use a rolling prefix summary as a last resort.

Raw history for each planned range is stored under:

.opencode/better-compact/sessions/<session-id>/<range-hash>.md

The model receives a reference to that file. Plans are range-hashed and replayed until prefix edits or context regrowth require a new plan.

License

AGPL-3.0-or-later