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 |
Requires @better-compact/pi 0.3.0 or newer.
omp plugin install @better-compact/pi
omp plugin doctorBetter Compact handles OMP's manual and automatic compaction. OMP still controls when compaction runs, along with retry, rollback, and accounting.
pi install npm:@better-compact/piRequires OpenCode 1.17.13 or newer.
opencode plugin better-compact --globalRestart OpenCode after installation.
Install the CLI:
npm install -g @better-compact/cliCompact a closed session and reopen it:
better-compact claude <session-id> --resumeInstall the companion plugin for /better-compact:compact:
claude plugin marketplace add AshishKumar4/better-compact
claude plugin install better-compact@better-compactLaunch Claude Code through the wrapper to compact and reopen automatically after exit:
better-compact claude --run| Platform | Command | Action |
|---|---|---|
| OMP, 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 preset |
| 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 |
| 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"
}pi also reads a trusted project override from .pi/better-compact.json. OMP reads the global file only.
OpenCode uses ~/.config/opencode/better-compact.jsonc and .opencode/better-compact.jsonc. See the OpenCode package README for its full schema.
- Inspect. Estimate the request, validate any stored plan, and choose a raw tail that must stay unchanged.
- Prune. Supersede repeated reads, stub old tool traffic, and remove old reasoning until the target fits.
- Summarize. Collapse selected assistant runs with a side-model call when pruning alone is not enough.
- 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.
| 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:
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm check:packageRun the OMP host smoke test after building:
pnpm --filter @better-compact/pi smoke:ompWorkspace 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.
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.
- Remove loaded skill text where the host exposes it in-band.
- Supersede repeated reads and remove stale failed-tool inputs.
- Replace old tool calls and results with short action stubs.
- Remove old reasoning if more space is needed.
- Remove remaining old tool traffic if more space is needed.
- Collapse selected assistant runs and summarize them with a side-model call.
- 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.
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 | 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.
Better Compact started as a fork of OpenCode Dynamic Context Pruning, originally published as @tarquinen/opencode-dcp.
AGPL-3.0-or-later