Pi-Dynamic-Context-Pruning

Cut LLM token spend in long Pi sessions, automatically. Dedup redundant tool calls, strip errored payloads, and let the model summarize closed work-streams — all without ever modifying your session history.

A faithful port of @tarquinen/opencode-dcp tailored to pi's extension API. Zero npm dependencies at runtime.

License: AGPL-3.0-or-later. Tests: 55 passing on Node 22 and 24.

Contents

• Why
• How it works
• Install
• Quick start
• Slash commands
• Configuration reference
• Per-model context limits
• Recipes
• Troubleshooting
• Develop
• How it differs from opencode-dcp
• Project layout
• Credits and license

Why

A long agentic loop in Pi typically wastes tokens on:

• Repeated lookups — the same grep or read re-issued five turns later
• Failed payloads — a 4-KB bash command that errored, sent back to the model on every subsequent turn
• Closed work-streams — initial repo scans, abandoned approaches, resolved retry loops whose raw output is no longer useful

pi-dcp prunes all three before the request hits the model. The on-disk session is never touched — pruning is applied to the request payload only, so /tree, /compact, fork, and resume all keep the originals intact.

How it works

A context event fires on every outbound LLM request. pi-dcp hooks that event, rewrites the request payload in-place, and lets it continue to the provider. The on-disk session is never mutated.

Three independent mechanisms run on the outbound request:

| Mechanism | What it does | When | |---|---|---| | Deduplication | Same toolName + canonical(args) keeps the newest result and replaces older copies with a [pruned by pi-dcp: duplicate ... call] marker. | Every LLM call (auto) | | Errored input purge | Failed tool calls have their arguments stripped after N turns. Error message is preserved. | Every LLM call (auto) | | compress tool | LLM-callable. Replaces a span of tool results with a lossless technical summary. Two modes: message (per-id list) or range (start and end span). | When the model decides |

Plus three nudge surfaces that bias the model toward compressing:

• Soft or strong in-system-prompt nudge when usage crosses minContextLimit
• Hard nudge above maxContextLimit
• Iteration nudge after N non-user messages without a user reply

Install

Three ways. Pick one:

npm (recommended — versioned, easy to update):

pi install npm:@davecodes/pi-dcp

git (always tracks main):

pi install git:github.com/Davidcreador/pi-dcp

manual clone (for hacking on the code):

git clone [email protected]:Davidcreador/pi-dcp.git ~/.pi/agent/extensions/pi-dcp

All three paths produce the same runtime behavior. Pi auto-discovers the extension via its pi.extensions package.json entry.

User state always lives at ~/.pi-dcp/, not next to the code. That directory holds:

~/.pi-dcp/
  config.json              your settings (written on first run from defaults)
  prompts/
    defaults/              regenerated each launch (read-only reference)
    overrides/             drop *.md files here to customize the LLM prompts
  dcp.log                  debug log (when config.debug is true)
  stats.json               lifetime savings counters

To update:

pi update npm:@davecodes/pi-dcp

Quick start

After install, run pi normally. Verify the extension is live:

pi -p "do you have a tool called 'compress'? answer yes/no"

Expected output: yes.

Open a long session as usual. Check savings any time with:

/dcp context     # this session
/dcp stats       # lifetime, across sessions

To bias the model toward compressing more aggressively, edit ~/.pi-dcp/config.json:

{
  "compress": {
    "minContextLimit": "30%",
    "maxContextLimit": "60%",
    "nudgeForce": "strong"
  }
}

minContextLimit is the soft-nudge floor. maxContextLimit is the hard-nudge ceiling. Restart pi after config changes.

Slash commands

| Command | What it does | |---|---| | /dcp | Show this command list | | /dcp context | Current session: token usage, DCP savings, active compressions | | /dcp stats | Lifetime savings across all pi sessions | | /dcp sweep [n] | Stage a compression over the last n tool results (default: since last user message). Use to nuke unwanted output. | | /dcp manual on/off/toggle/status | Runtime manual mode — stops the LLM from auto-compressing. Edit config.json to persist. | | /dcp decompress <id> | Temporarily restore a stored compression's original tool outputs | | /dcp recompress <id> | Re-apply a previously decompressed entry |

Slash commands work in interactive pi mode only — pi -p (print mode) does not dispatch them. The compress tool and auto strategies work in both modes.

Configuration reference

Defaults are written to ~/.pi-dcp/config.json on first run. Per-project overrides at <repo>/.pi/dcp.json shallow-merge on top. Restart pi after edits.

The shipped defaults are tuned for real-world long sessions — see config.example.json in this repo for the exact reference shape and inline comments.

{
  "enabled": true,
  "debug": false,
  "pruneNotification": "minimal",

  "experimental": {
    "customPrompts": false
  },

  "manualMode": {
    "enabled": false,
    "automaticStrategies": true
  },

  "turnProtection": {
    "enabled": true,
    "turns": 3
  },

  "compress": {
    "mode": "range",
    "permission": "allow",
    "minContextLimit": 30000,
    "maxContextLimit": 70000,
    "modelMinLimits": {
      "anthropic/claude-opus-4-7": 35000
    },
    "modelMaxLimits": {
      "anthropic/claude-opus-4-7": 85000
    },
    "nudgeEveryTurns": 5,
    "nudgeFrequency": 3,
    "iterationNudgeThreshold": 8,
    "nudgeForce": "strong",
    "protectedTools": []
  },

  "strategies": {
    "deduplication": {
      "enabled": true,
      "protectedTools": []
    },
    "purgeErrors": {
      "enabled": true,
      "turns": 2,
      "protectedTools": []
    }
  }
}

Field notes:

• pruneNotification: off, minimal, or detailed (reserved).
• experimental.customPrompts: when true, honors prompts/overrides/*.md.
• manualMode.automaticStrategies: when manual mode is on, still run dedup and purge.
• turnProtection.turns: last N user-bounded turns are immune to pruning.
• compress.minContextLimit / maxContextLimit: number of tokens or a "X%" string of the model's context window.
• compress.nudgeEveryTurns: per-turn soft-nudge throttle.
• compress.nudgeFrequency: per-request soft-nudge throttle (stacks with the per-turn one).
• compress.iterationNudgeThreshold: 0 disables; fires after N messages since the last user message.
• compress.nudgeForce: soft or strong wording.
• strategies.purgeErrors.turns: turns after which errored args are purged.

Always protected (never pruned, regardless of config): compress, write, edit, todo, task, skill.

Per-model context limits

compress.modelMinLimits and modelMaxLimits accept keys shaped as provider/id, matching ctx.model.provider and ctx.model.id. Examples mirroring the shipped config.json:

| Model | Window | Soft floor | Hard ceiling | Strategy | |---|---|---|---|---| | anthropic/claude-haiku-4-5 | 200k | 30k | 70k | tight — cheap fast tier | | anthropic/claude-sonnet-4-5 | 200k | 50k | 120k | workhorse band | | anthropic/claude-sonnet-4-6 | 200k | 50k | 120k | workhorse band | | anthropic/claude-opus-4-1 to 4-7 | 200k | 35k | 85k | aggressive — save expensive tokens | | openai/gpt-5.4-mini-fast | — | 25k | 50k | tightest | | openai/gpt-5.4-mini | — | 30k | 70k | tight | | openai/gpt-5.5 | — | 45k | 100k | medium |

Values accept either a number (absolute token count) or a "X%" string (percentage of the model's context window).

Recipes

Save tokens aggressively on premium models

{
  "compress": {
    "modelMinLimits": { "anthropic/claude-opus-4-7": "10%" },
    "modelMaxLimits": { "anthropic/claude-opus-4-7": "25%" },
    "nudgeForce": "strong"
  }
}

Do not auto-compress, let me drive

{
  "manualMode": { "enabled": true, "automaticStrategies": true }
}

Auto-dedup and purge still run. You drive compression via /dcp sweep.

Project-specific overrides

Drop a .pi/dcp.json in the repo root:

{
  "strategies": {
    "purgeErrors": {
      "turns": 1,
      "protectedTools": ["lint"]
    }
  }
}

Customize the nudge wording

{
  "experimental": { "customPrompts": true }
}

Then create ~/.pi-dcp/prompts/overrides/strong-nudge.md with your text. Restart pi.

Troubleshooting

The compress tool is not showing up:

• Confirm with pi -p "list your tools" 2>&1 | grep compress. If missing, check compress.permission is not "deny".
• Restart pi after any config change. Extensions load once at startup.

Nothing is being pruned:

• /dcp context shows live stats. If always 0:
  • turnProtection.turns may cover your whole session (recent turns are protected).
  • strategies.*.enabled may be false.
  • You may be hitting protected tools — write and edit are never deduped.

See what is happening under the hood:

{ "debug": true }

Restart pi. Logs land at ~/.pi-dcp/dcp.log:

[2026-05-13T...] INFO pi-dcp initialized {"mode":"range",...}
[2026-05-13T...] INFO pipeline applied {"dedupPruned":2,"errorInputsPurged":1,"tokensSaved":3214}

Compress tool refuses with protected_window_overlap:

• The model picked tool-call IDs that live inside turnProtection.turns. Either lower turnProtection.turns, disable it, or tell the model to pick older calls.

Develop

cd ~/.pi/agent/extensions/pi-dcp

# Set up dev deps (peer + typescript)
npm install --no-save typescript @earendil-works/pi-coding-agent

# Typecheck + test
npm run check
npm run test

CI on GitHub Actions runs the same on Node 22 and 24 against every push and PR.

How it differs from opencode-dcp

| Feature | opencode-dcp | pi-dcp | |---|---|---| | Tokenizer | @anthropic-ai/tokenizer | ctx.getContextUsage() (built-in) | | Auto-update | npm latest check | git pull | | Soft/hard nudges | per-request injection | before_agent_start system-prompt addendum (functionally equivalent) | | compress.mode (range, message) | both | both | | turnProtection | runtime skip | runtime skip plus upfront refusal of compress tool overlap | | modelMinLimits and modelMaxLimits | yes | yes | | iterationNudgeThreshold | yes | yes | | nudgeForce | yes | yes | | compress.nudgeFrequency | yes | yes, plus per-turn nudgeEveryTurns | | Prompt overrides | yes | yes | | manualMode.automaticStrategies | yes | yes | | Skipped in pi-dcp | — | pruneNotificationType:"toast", compress.showCompression, compress.summaryBuffer, experimental.allowSubAgents, protectedFilePatterns |

Project layout

pi-dcp/
  index.ts                          extension entry — wires hooks, tool, /dcp command
  config.json                       runtime config (auto-generated; tracked)
  lib/
    config.ts                       loader, DEFAULT_CONFIG, percent + per-model resolution
    logger.ts                       ~/.pi-dcp/dcp.log writer (gated by config.debug)
    state.ts                        per-session in-memory state
    stats.ts                        ~/.pi-dcp/stats.json lifetime counters (atomic write)
    messages.ts                     AgentMessage helpers + canonical JSON + cloneForMutation
    pipeline.ts                     orchestrates strategies + applies compressions
    nudges.ts                       soft/strong/hard/iteration system-prompt addendums
    strategies/
      deduplication.ts              drop redundant tool calls
      purge-errors.ts               strip errored tool inputs after N turns
    tools/
      compress-message.ts           LLM tool — per-id mode
      compress-range.ts             LLM tool — span mode
      shared.ts                     preflight, storeCompression, branchToolCallIds
    prompts/
      index.ts                      PromptStore + defaults + override loader
    commands/                       /dcp subcommand handlers
      help.ts
      context.ts
      stats.ts
      manual.ts
      sweep.ts
      decompress.ts                 decompress + recompress
  test/                             55 unit tests, zero external deps
    pipeline.test.ts                dedup, purge, mutation safety, idempotency
    misc.test.ts                    config percent parsing, nudge throttling, parseStrictId
    features.test.ts                range mode, prompt overrides, manual modes, nudgeFreq
    parity.test.ts                  turnProtection, modelMin/Max, iterationNudge, nudgeForce
    audit.test.ts                   edge cases (no-user, iter-refire, protected overlap)
  skills/pi-dcp/SKILL.md            documentation surface pi reads at session start
  prompts/defaults/                 regenerated on every init (read-only reference)
  prompts/overrides/                you put files here when customPrompts is true
  .github/workflows/ci.yml          Node 22/24 matrix typecheck + test
  README.md

Credits and license

Concept and prompt design ported from @tarquinen/opencode-dcp by tarquinen. Pi adaptation and tests by @Davidcreador.

License: AGPL-3.0-or-later — inherits from upstream. See LICENSE.