pi-context-pruning

A pi extension that proactively prunes old tool outputs from LLM context to reduce token usage.

Pruning algorithm ported from OpenCode.

The Problem

Pi sends all tool outputs (file reads, bash output, grep results, etc.) to the LLM until the context window fills up and compaction triggers. This means:

• Long sessions accumulate massive context from stale tool outputs
• Token usage grows linearly until forced compaction
• You pay for tokens the LLM doesn't need (old file contents, superseded grep results)

OpenCode solves this by proactively pruning old tool outputs after every turn, keeping context lean. This extension brings that same strategy to pi.

Install

# From local clone
pi install /path/to/pi-context-pruning

# Or from the repo directory
pi install .

After installing, /reload or restart pi.

Enable / Disable

Enabled by default. Toggle via settings.json (global or project):

// ~/.pi/agent/settings.json (global) or .pi/settings.json (project)
{
  "contextPruning": {
    "enabled": false
  }
}

Project settings override global. Changes take effect on /reload or next session.

How It Works

Before pruning (what pi normally sends):
┌────────┬──────┬───────┬──────┬───────┬──────┬───────┬──────┬───────┐
│ system │ user │ asst  │ tool │ user  │ asst │ tool  │ asst │ tool  │
│ prompt │  #1  │  #1   │ 50KB │  #2   │  #2  │ 30KB  │  #3  │ 10KB  │
└────────┴──────┴───────┴──────┴───────┴──────┴───────┴──────┴───────┘
                         ↑ stale, expensive

After pruning (what the LLM actually sees):
┌────────┬──────┬───────┬──────────────────┬──────┬───────┬──────┬───────┐
│ system │ user │ asst  │ [pruned ~12.5K   │ user │ asst  │ tool │ tool  │
│ prompt │  #1  │  #1   │  tokens | read]  │  #2  │  #2   │ 30KB │ 10KB  │
└────────┴──────┴───────┴──────────────────┴──────┴───────┴──────┴───────┘
                         ↑ tiny marker          recent context preserved ↑

Algorithm (ported from OpenCode's compaction.ts)

Before each LLM call, via pi's context event:

1. Walk messages backward from newest
2. Skip recent turns — last 2 user turns are fully protected
3. Stop at compaction boundary — already-summarized content is untouched
4. Accumulate tool output tokens — first 40K tokens of older tool outputs are protected
5. Beyond 40K → replace tool output content with a short marker:

   [output pruned — ~12,500 tokens | read path="src/components/App.tsx"]
   

6. Only prune if worthwhile — minimum 20K tokens must be prunable

Key Properties

• Non-destructive: Session file keeps full history. Only the LLM sees pruned content.
• Preserves tool call metadata: The LLM still knows which tools were called and with what arguments.
• Complements compaction: Runs alongside pi's built-in compaction — pruning reduces token usage between compactions.
• Error outputs protected: Tool results with isError: true are never pruned (diagnostics matter).
• Re-readable: If the LLM needs old file contents, it can re-read the file. The marker tells it what was there.

Commands

Command	Description
/prune	Force prune now — bypasses minimum threshold, runs on next LLM call
/prune-toggle	Toggle pruning on/off for the current session
/prune-stats	Show pruning statistics for the current session
/prune-config	Show current pruning configuration

Status Bar

The footer shows live pruning status:

🔪 45.2K tool tokens scanned | pruned ~25.0K | 8 protected

Configuration

Edit extensions/context-pruning/config.ts in the installed package:

Constant	Default	Description
PRUNE_MINIMUM	20,000	Minimum prunable tokens before acting
PRUNE_PROTECT	40,000	Token budget for protected older tool outputs
PROTECTED_TURNS	2	Recent user turns to never prune
PROTECTED_TOOLS	[]	Tool names that are never pruned
PRUNABLE_TOOLS	["read", "bash", "grep", "find", "ls", "edit", "write"]	Tools eligible for pruning

Tuning Guide

• More aggressive pruning: Lower PRUNE_PROTECT (e.g., 20_000) and/or PRUNE_MINIMUM (e.g., 10_000)
• Less aggressive: Raise PRUNE_PROTECT (e.g., 80_000) or increase PROTECTED_TURNS
• Protect extension tools: Add tool names to PROTECTED_TOOLS
• Prune everything: Set PRUNABLE_TOOLS to [] (empty = all non-protected tools are prunable)

How This Differs From Pi's Built-in Compaction

Feature	Pi Compaction	Context Pruning
When	Context exceeds threshold	Every LLM call
What	Summarizes old messages via LLM	Replaces old tool outputs with markers
Cost	Requires LLM call for summary	Zero — no LLM calls
Persistence	Modifies session (adds CompactionEntry)	Non-destructive (session unchanged)
Granularity	Entire conversation turns	Individual tool outputs

They work together: pruning keeps context lean between compactions, so compaction triggers less often (or not at all for shorter sessions).

Architecture

extensions/context-pruning/
├── index.ts      # Extension entry — context hook, commands, status
├── pruner.ts     # Pure pruning function (testable, no side effects)
└── config.ts     # Configuration constants, types, and settings loader

No dependencies — only uses estimateTokens from @mariozechner/pi-coding-agent (available at runtime via pi).

Credits

Pruning algorithm ported from OpenCode. Thanks to the OpenCode team.

See also: opencode-dynamic-context-pruning