Better Compact

Install · Commands · How it works · Architecture

_{Edited and maintained by Claude. Provided as-is.}

Most coding agents wait until the context is full, then replace the old conversation with one summary. Exact tool output, failed attempts, user wording, and decision history disappear together.

Better Compact reduces context in stages. It removes stale tool traffic and old reasoning first, summarizes selected assistant runs only when needed, and keeps the raw history on disk for recall.

Plain compaction	Better Compact
One summary replaces the old conversation	Each pruning stage runs only when needed
Tool calls and failures lose their structure	Removed tools leave action stubs with status and errors
Exact old output is unavailable	Raw history stays on disk with a model-readable reference
Every compaction changes the prefix	Validated plans replay the same stable prefix

Install

Oh My Pi

Requires @better-compact/pi 0.3.1 or newer.

omp plugin install @better-compact/pi
omp plugin doctor

Better Compact handles OMP's manual and automatic compaction. OMP still controls when compaction runs, along with retry, rollback, and accounting.

pi

pi install npm:@better-compact/pi

OpenCode

Requires OpenCode 1.17.13 or newer.

opencode plugin better-compact --global

Restart OpenCode after installation.

Claude Code

Install the CLI:

npm install -g @better-compact/cli

Compact a closed session and reopen it:

better-compact claude <session-id> --resume

Install the companion plugin for /better-compact:compact:

claude plugin marketplace add AshishKumar4/better-compact
claude plugin install better-compact@better-compact

Launch Claude Code through the wrapper to compact and reopen automatically after exit:

better-compact claude --run

Commands

Platform	Command	Action
OMP	/better-compact	Run the selected committed compaction
pi, OpenCode	/better-compact	Run Better Compact now
OMP	/better-compact-report	Show the active plan
OMP, pi, OpenCode	/better-compact-settings	Open settings
OMP, pi	/better-compact-preset <light|moderate|max>	Change the pruning preset
OMP	/better-compact-mode <better-compact|omp>	Choose the owner for new sessions
OpenCode	/better-compact context	Show context usage
OpenCode	/better-compact stats	Show the active plan
Claude Code	/better-compact:compact	Queue compaction for session exit

Presets

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

The trigger starts a pruning pass. The target is the desired context size after the pass.

For pi and OMP, create <agent-dir>/better-compact.json:

{
    "automatic": true,
    "preset": "moderate",
    "summaryEffort": "inherit",
    "ompCompactionOwner": "better-compact"
}

pi also reads a trusted project override from .pi/better-compact.json. OMP reads the global file only.

On OMP, set ompCompactionOwner to omp and restart to keep Better Compact request pruning while restoring OMP's full compaction.methodOrder and async speculation. Set automatic to false as well for pure OMP behavior.

OpenCode uses ~/.config/opencode/better-compact.jsonc and .opencode/better-compact.jsonc. See the OpenCode package README for its full schema.

How does it work?

1. Inspect. Estimate the request, validate any stored plan, and choose a raw tail that must stay unchanged.
2. Prune. Supersede repeated reads, stub old tool traffic, and remove old reasoning until the target fits.
3. Summarize. Collapse selected assistant runs with a side-model call when pruning alone is not enough.
4. Preserve. Write the affected raw history to disk, insert a reference, and replay the same plan on later requests.

Better Compact escalates one stage at a time. A light pass can stop after pruning old tools. A heavy pass can continue through reasoning, assistant-run summaries, and a rolling prefix summary.

Packages

Package	Purpose
better-compact	OpenCode plugin
@better-compact/pi	OMP and pi extension
@better-compact/cli	Claude Code session CLI
@better-compact/core	Shared pruning engine

Platform-specific instructions:

• OpenCode
• OMP and pi
• Claude Code CLI
• Claude Code plugin

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm check:package

Run the OMP host smoke test after building:

pnpm --filter @better-compact/pi smoke:omp

Workspace layout:

packages/
├── core/         shared engine and message IR
├── opencode/     OpenCode server and TUI plugins
├── pi/           OMP and pi entrypoints
├── cli/          Claude Code CLI
└── claude-code/  Claude Code slash command plugin

See RELEASING.md for release tags and npm publishing.

Architecture

Each adapter converts its native messages to a shared turn/item model, runs the pruning engine, then converts the result back to the host format.

native messages
      │
      ▼
platform codec
      │
      ▼
turns and items
      │
      ▼
pruning plan
      │
      ▼
platform codec
      │
      ▼
outgoing context

Native payloads stay attached to IR items as opaque handles. Unchanged content is returned without reconstruction. Tool calls and tool results are paired into one item, so pruning cannot leave an orphaned result.

Pruning order

1. Remove loaded skill text where the host exposes it in-band.
2. Supersede repeated reads and remove stale failed-tool inputs.
3. Replace old tool calls and results with short 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 with a side-model call.
7. Replace the old prefix with a rolling summary as a last resort.

The engine keeps a raw tail of recent user turns and tool work. It also preserves the latest in-band todo state where the host exposes one.

Plans and recall

A plan records the compacted range, tail boundary, applied stages, summaries, token counts, and transcript path. A range hash validates the plan before replay. Appending a small tail reuses the same transformed prefix. Editing the old prefix invalidates it. Large regrowth builds a new plan without restoring content removed by the previous plan.

Before applying a plan, Better Compact writes the affected raw history to disk and inserts a reference into the model context. The model can read that file when exact output or wording is needed.

Host integration

Host	Application model	Durable history
OpenCode	Virtual plan on each request	Unchanged
OMP	Request plan plus custom compaction result	OMP writes a compaction entry
pi	Virtual plan on each request	Unchanged
Claude Code	Closed-session rewrite	Backed up before replacement

The OMP and pi adapters share the runtime, codec, config, plan store, ownership logic, transcript storage, and TUI components. Their entrypoints contain only host APIs and behavior that differs between the two hosts.

Upstream

Better Compact started as a fork of OpenCode Dynamic Context Pruning, originally published as @tarquinen/opencode-dcp.

License

AGPL-3.0-or-later