sting8k/pi-vcc

What is pi‑vcc?

pi‑vcc is a plug‑in for the Pi coding‑assistant (the open‑source LLM‑powered chatbot that helps you write code). It automatically compresses long chat histories into a concise, searchable summary without calling any language model. The summary is built by extracting key information from the conversation (goals, changed files, recent commits, commands run, open problems, user preferences, and a short transcript) and formatting it into fixed sections.

---

Why use it?

Feature	Pi’s built‑in compaction	pi‑vcc
Method	Sends the whole cut to an LLM for a generated summary	Pure algorithmic extraction – no LLM, no token cost
Determinism	Non‑deterministic, can hallucinate	Same input → identical output
Size reduction	Varies	Median 97.6 % reduction (89 % at the 10th percentile)
Latency	Wait for an LLM call (seconds)	Median 1 ms, 90 %‑tile 11 ms, worst‑case 348 ms
Cost	Burns tokens on the summarisation request	Free
History after compaction	Discarded	Still searchable via vcc_recall
Repeated compactions	May lose more each time	Sections merge and stay capped
Structure	Free‑form prose	Up to six labelled sections + a brief transcript

The plugin also replaces Pi’s default /compact command, adds its own /pi‑vcc command for on‑demand compaction, and can intervene in automatic compactions.

---

How to get it

# From the npm registry
pi install npm:@sting8k/pi-vcc

# Or directly from GitHub
pi install https://github.com/sting8k/pi-vcc

# Or run it without installing
pi -e https://github.com/sting8k/pi-vcc

---

Using the plugin

• Automatic – when the context window fills, pi‑vcc compacts the oldest part of the conversation.
• On‑demand – type /pi‑vcc to compact immediately, keeping the last user turn.
• Tail control – /pi‑vcc keep:N [prompt] keeps the last N user turns (e.g. keep:0 compacts everything) and can send an optional prompt to the agent after summarising.
• Fallback – set overrideDefaultCompaction: false in the config to let Pi’s core handle normal /compact while still allowing /pi‑vcc.

---

What the summary looks like

[Session Goal]
- Fix the authentication bug in login flow
- [Scope change]
- Also update the session token refresh logic

[Files And Changes]
- Modified: src/auth/session.ts
- Created: tests/auth-refresh.test.ts

[Commits]
- a1b2c3d: fix(auth): refresh token after password reset

[Tracked Commands]
- docker: docker compose restart api 2>&1

[Outstanding Context]
- lint check still failing on line 42

[User Preferences]
- Prefer Vietnamese responses
- Always run tests before committing

---
...(28 earlier lines omitted)
[user]
Fix the auth bug, users can't log in after password reset

[assistant]
Root cause is a missing token refresh after password reset... (#11)
* bash "bun test tests/auth.test.ts" (#12)
* edit "src/auth/session.ts" (#14)
* bash "docker compose restart api 2>&1" (#15)
* bash "bun test tests/auth.test.ts" (#16)
---
Use `vcc_recall` to search for prior work, decisions, and context from before this summary.

Only sections that have content appear; a session with no commits simply omits the [Commits] block.

---

Searching the hidden history – vcc_recall

Even after a part of the conversation is compacted away, you can retrieve it:

vcc_recall({ query: "auth token" })          // keyword OR search, ranked
vcc_recall({ query: "auth token", page: 2 }) // pagination (5 results per page)
vcc_recall({ query: "hook|inject" })        // regex fallback
vcc_recall({ query: "auth token", scope: "all" }) // search all lineages

// Direct range or expansion
vcc_recall({ range: [1250, 1290] })
vcc_recall({ expand: [1253] })

The same functionality is exposed as a slash command, e.g. /pi‑vcc‑recall auth token scope:all.

---

How it works (no AI involved)

1. Pick the cut – everything before the kept tail is the material to summarise.
2. Normalize – turn Pi messages into uniform blocks, drop system messages and empty blocks.
3. Extract & format – pull out the six possible sections and a brief transcript, then render them.
4. Merge – if a previous summary exists, merge the new sections into it and re‑cap. Token counts are estimated from Pi’s own statistics; no external model is called.

---

Configuration (pi‑vcc‑config.json)

Located in ~/.pi/agent (or $PI_CODING_AGENT_DIR). Default values are created on first run:

{
  "overrideDefaultCompaction": true,
  "smartKeepTail": true,
  "continueAfterThresholdCompact": true,
  "debug": false,
  "skipForProviders": [],
  "skipCustomTypes": [],
  "trackCommands": []
}

• overrideDefaultCompaction – let pi‑vcc replace Pi’s /compact and automatic compactions.
• smartKeepTail – expands the kept tail up to 25 k tokens when the default keep:1 tail is tiny.
• continueAfterThresholdCompact – after an automatic compaction, tell the agent to keep going (relevant for older Pi versions).
• debug – writes detailed per‑compaction diagnostics to /tmp/pi‑vcc‑debug.json.
• skipForProviders – list provider IDs (e.g. groq, openai) for which pi‑vcc steps aside.
• skipCustomTypes – omit custom message types from the summary input.
• trackCommands – specify shell commands to retain in the [Tracked Commands] section (e.g. ["docker", "kubectl"]).

---

Benchmarks

The repository includes a benchmarks/README.md that compares pi‑vcc (v0.3.18) against Pi’s default compactor on 1,884 real sessions, reporting metrics such as recall, fact density, precision, and size reduction.

---

Who built it?

• Inspired by the VCC (View‑oriented Conversation Compiler) project.
• Recall‑related features (mode:"touched", #N:path) are borrowed from pi‑blackhole by @k0valik.
• Auto‑continue logic comes from a fork by @monotykamary.

---

License

MIT – free to use, modify, and distribute.

---

TL;DR

pi‑vcc gives you a fast, deterministic, zero‑cost way to shrink long Pi chat sessions into a structured summary while keeping the full history searchable. Install it via pi install npm:@sting8k/pi-vcc, let it run automatically or trigger it with /pi‑vcc, and use vcc_recall to dig back into the compacted parts whenever you need to.