@better-compact/pi

Better Compact for Oh My Pi and pi.

It prunes old tool output and reasoning, keeps recent work intact, stores removed context on disk, and summarizes assistant turns only when needed.

Install

Oh My Pi

Requires Oh My Pi 18 or newer. An OMP build with the in-place rewrite seam keeps history as real messages; stock OMP receives a summary compaction.

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

pi

pi install npm:@better-compact/pi

Local development

pnpm build
omp plugin install ./packages/pi

OMP links the local directory, so later builds are used without reinstalling.

Install the package through one source only. Do not combine a plugin install with a manual drop-in.

Commands

Command	OMP	pi	Action
/better-compact	yes	yes	Compact now
/better-compact-report	yes	no	Show the active plan
/better-compact-settings	yes	yes	Open settings
/better-compact-preset <light|moderate|max>	yes	yes	Change the pruning preset
/better-compact-mode <better-compact|omp>	yes	no	Choose the owner for new sessions

OMP runs /better-compact through its normal compaction lifecycle. The active owner decides which algorithm supplies the result. Owner changes require an OMP restart. pi stores a plan that starts on the next request.

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.

Configuration

Create <agent-dir>/better-compact.json:

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

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

OMP compaction owner

Choose who supplies the durable compaction:

/better-compact-mode better-compact
/better-compact-mode omp

Restart OMP after changing the owner. Native OMP speculation is enabled only when no session_before_compact extension hook is registered.

automatic	ompCompactionOwner	Result after restart
true	better-compact	Better Compact prunes requests and supplies committed compaction
true	omp	Better Compact prunes requests; OMP runs its native method order
false	better-compact	No request pruning; Better Compact supplies committed compaction
false	omp	Pure OMP behavior, including async speculation

OMP native method order

OMP 18 uses an ordered fallback list:

omp config get compaction.methodOrder
omp config set compaction.methodOrder '["remote","snapcompact","handoff","shake","soft"]'

Methods run from left to right. Unavailable or failed methods advance to the next one.

Method	Action
remote	Use provider-native OpenAI-compatible compaction when available
snapcompact	Archive old text as image frames
handoff	Generate a handoff and continue from it
shake	Elide heavy tool results and blocks with artifact recovery
soft	Summarize the old prefix with a compaction model

Disable automatic compaction with:

omp config set compaction.enabled false

When ompCompactionOwner is omp, Better Compact registers no compaction hook. OMP keeps its full fallback order and async speculation. When the owner is better-compact, Better Compact supplies committed results; shake can still run before the hook when it appears earlier in the method order.

pi native compaction

pi cannot accept a custom compaction result. Disable its native compaction if Better Compact should be the only context reducer:

{
    "compaction": {
        "enabled": false
    }
}

Behavior

Oh My Pi

Better Compact can run at two independent points:

1. The context hook applies a virtual pruning plan to outgoing requests when automatic is enabled.
2. The session_before_compact hook supplies OMP's committed result when the active startup owner is better-compact.

Set ompCompactionOwner to omp and restart to keep request pruning while restoring OMP's complete method order and async speculation.

OMP keeps control of timing, retry, rollback, headroom checks, continuation, and provider history.

When Better Compact owns committed compaction, the pruned prefix keeps:

• user turns as written;
• dropped tool calls reduced to short action stubs;
• selected assistant runs replaced by summaries;
• a reference to the raw transcript on disk;
• the recent tail unchanged, sized by a token budget rather than a turn count.

How that prefix is persisted depends on the host. An OMP build with the in-place rewrite seam (supportsRewrite on the compaction event) receives each kept entry rewritten in place: user messages stay user messages and no entry is folded into a summary. Stock OMP receives the same prefix as one summary over a whole-turn boundary, the only shape it can persist. The last-resort prefix summary is off by default; set custom.prefixSummary to true to allow it.

OMP uses its native methods when it owns compaction, when Better Compact cannot produce a valid boundary, or when a pass would free less than the no-progress dead-band.

summaryEffort accepts off to skip side-model summaries; collapsed runs then carry a deterministic preview and the transcript pointer.

pi

Better Compact stores a branch-local plan and applies it to outgoing requests. The plan survives resume and forks when the stored prefix still matches the live branch.

Files

Transcripts are written under the host session directory:

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

Configuration is stored at:

<agent-dir>/better-compact.json

Plans are stored as better-compact-plan custom session entries.

Development

From the repository root:

pnpm install
pnpm --filter @better-compact/pi typecheck
pnpm --filter @better-compact/pi test
pnpm --filter @better-compact/pi build
pnpm --filter @better-compact/pi smoke:omp

smoke:omp loads the built OMP artifact against the real host runtime and exercises request pruning and committed compaction.

Architecture

One npm package ships two entrypoints:

Host	Entry	Manifest
OMP	dist/omp.js	omp.extensions
pi	dist/extension.js	pi.extensions

OMP prefers the omp manifest. pi reads the pi manifest. Each bundle imports only its host package scope.

Most code is shared:

src/
├── runtime.ts       config, plans, pruning, summaries, widget state
├── codec.ts         shared pi-family codec
├── messages.ts      shared message model
├── ownership.ts     one active instance per session
├── plan-store.ts    branch-local plan persistence
├── config.ts        config loading and writing
├── transcripts.ts   transcript storage
├── tui/             report, settings, widget
├── extension.ts     pi host wiring
├── omp.ts           OMP host wiring and compaction hook
└── omp/             OMP conventions and summary transport

Pruning order

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

Tool calls and results are paired before pruning. The latest OMP todo state is preserved when its tool result leaves the request.

A range hash validates each stored plan before replay. Prefix edits invalidate it. Tail growth reuses it until the context crosses the trigger again.

License

AGPL-3.0-or-later