pi-omni-compact

A pi extension that replaces default context compaction with a large-context model subprocess. Pi normally summarizes with the active conversation model. This extension spawns a separate pi instance using a large-context model that reads the entire conversation at once, producing higher-fidelity summaries.

Installation

pi install npm:pi-omni-compact

Or from git:

pi install git:github.com/Whamp/pi-omni-compact

Requirements

• pi installed
• An API key for a large-context model configured in pi's model registry

Configuration

Edit settings.json in the extension directory to configure which models to try. The extension uses the first model with a valid API key:

{
  "models": [
    { "provider": "google-antigravity", "id": "gemini-3-flash", "thinking": "high" },
    { "provider": "google-antigravity", "id": "gemini-3-pro-low", "thinking": "high" }
  ],
  "debugCompactions": false,
  "minSummaryChars": 100
}

You will need to update the models array to match a provider and model available in your pi setup. A model with a 1M+ token context window is highly recommended — the whole point is reading the full conversation at once.

| Setting | Default | Description | |---------|---------|-------------| | models | See above | Ordered list of models to try. First with a valid API key wins. | | debugCompactions | false | Save input/output JSON to ~/.pi/agent/extensions/pi-omni-compact/compactions/ for diagnosing bad summaries. | | minSummaryChars | 100 | Minimum summary length. Shorter output triggers fallback to default compaction. |

API keys are resolved through pi's model registry — no separate key configuration needed.

Optional: pi-read-map

If you have pi-read-map installed, the summarizer subprocess will use it automatically. It provides structural file maps so the summarizer can navigate the codebase faster and produce more accurate summaries.

How it works

The extension hooks two pi events:

• session_before_compact — fires when the context window fills up and pi needs to summarize conversation history
• session_before_tree — fires when the user abandons a conversation branch and pi needs to preserve what happened

For both events, the extension:

1. Analyzes the full session for structural metadata — tool usage patterns, friction signals (error loops, rephrasing cascades), file operations, and session boundaries
2. Serializes the conversation and metadata into a hybrid text format
3. Resolves the first configured model with a valid API key
4. Spawns a pi subprocess with read-only tools (read, grep, find, ls) and pi-read-map if installed
5. The subprocess reads the conversation and referenced source files, then returns a structured summary

On any failure — no API key, subprocess crash, output too short — the extension returns undefined and pi falls back to its default compaction.

Summary format

The output follows a fixed structure:

• Goal — the original user request, quoted verbatim
• Constraints & Preferences — requirements and style decisions
• Progress — done, in progress, blocked
• Key Decisions — what was decided, why, and alternatives rejected
• File Changes — paths and what changed
• Code Patterns Established — conventions and architectural choices the codebase follows
• Implicit Dependencies — environment variables, config, non-obvious coupling
• Open Questions — deferred decisions, unresolved issues
• Error History — errors encountered and fixes applied
• Remaining Work — unfinished tasks
• Next Steps — ordered list of recommended actions
• Critical Context — specific values, references, and data needed to continue

Benchmark results

Evaluated against 14 real coding sessions (25k–165k tokens) using pi-compression-benchmark with probe-response scoring:

| Strategy | Avg Score | Min | Max | |----------|-----------|-----|-----| | pi-omni-compact | 57.1 | 35 | 89 | | pi-agentic-compaction | 46.2 | 30 | 70 | | pi-default | 46.1 | 20 | 85 |

Strongest on sessions with concrete implementation work. Weakest on pure exploration/research sessions with no clear goal structure.

Development

npm run validate   # typecheck + lint + format check
npm test           # unit + integration tests
npm run test:e2e   # end-to-end tests (requires real API key)
npm run build      # compile to dist/

Architecture

src/
  index.ts              Event handlers for session_before_compact, session_before_tree
  models.ts             Resolve first configured model with valid API key
  serializer.ts         Convert pi messages to LLM input format
  session-analysis.ts   Extract structural metadata (friction, boundaries, file ops)
  prompts.ts            System prompts (initial, incremental, branch)
  subprocess.ts         Spawn pi subprocess, parse JSON event stream
  settings.ts           Load and validate settings.json
  debug.ts              Save compaction input/output as debug artifacts

License

MIT