pi-airgun

Two pi extensions for LLM context compression and Anthropic prompt caching. Zero LLM inference cost. No build step.

Install

# From GitHub
pi install github:blai/pi-airgun

# From npm
pi install npm:pi-airgun

Extensions

compress — Context Compressor

Intercepts every tool result and the LLM context window to remove token waste through a two-pipeline architecture.

Footer widget: 🗜 ~1,234 tok saved (28%) Command: /compress-stats — per-session breakdown (tiktoken-exact for immediate, ÷3.5 estimate for deferred)

Two-pipeline architecture

The split exists because some compressions are safe to persist (improve human readability) while others would be confusing in the UI and session files.

| Pipeline | Hook | Stages | Persisted to session? | Token tracking | | ------------- | --------------------- | -------------------------------------------- | --------------------- | -------------- | | Immediate | tool_result | ansi → whitespace | ✅ yes | tiktoken exact | | Deferred | context (deep copy) | sep-norm → dedup → paths → toon → dyn-tokens | ❌ no (LLM only) | ÷3.5 estimate |

Immediate stages (tool_result — what you see in the TUI)

| Stage | What it removes | Why safe to persist | | -------------- | ----------------------------------- | ------------------------------------------------------------------- | | ansi | \x1b[31m…\x1b[0m escape codes | Noise in both UI and session files — stripping improves readability | | whitespace | Trailing spaces, 3+ blank lines → 2 | Improves TUI output density |

Uses node:util.stripVTControlCharacters (Node 16.11+ built-in, zero deps).

Deferred stages (context hook — LLM only, originals in TUI)

| Stage | What it does | Why deferred only | | -------------- | ---------------------------------------------------- | ------------------------------------------------- | | sep-norm | Long separator lines → 8 chars | Confusing to read truncated separators in TUI | | dedup | [4×] same line markers | Markers confusing to read in TUI | | paths | $WS/$HOME sigils + legend | Sigils confusing in TUI | | toon | JSON → TOON format | Different syntax, unreadable without knowing TOON | | dyn-tokens | Dynamic $T1, $T2 sigils for repeated long tokens | Confusing without legend context |

TOON (Token-Oriented Object Notation) collapses uniform JSON arrays into CSV-style tables:

# Before (JSON, 2680 chars)               # After (TOON, 858 chars, −68%)
[{"id":1,"name":"User 0","role":"admin"},  users[20]{id,name,role,active}:
 {"id":2,"name":"User 1","role":"user"},    1,User 0,admin,true
 ...]                                       2,User 1,user,true
                                            ...

Lossless round-trip. Only applied when TOON is ≥10% shorter.

Dependencies

| Package | Version | Purpose | | ------------------- | ------- | -------------------------------------- | | @toon-format/toon | ^2.1.0 | JSON → TOON encoding | | js-tiktoken | ^1.0.21 | Exact BPE token counting (cl100k_base) |

cache — Anthropic Prompt Caching

Adds cache_control: { type: "ephemeral" } to every Anthropic API request, enabling automatic caching.

How it works: Anthropic places the cache breakpoint at the last cacheable block automatically and moves it forward as the conversation grows. On a cache hit, the cached prefix is charged at 10% of normal input token price.

Economics: ~2-3 turn break-even. From turn 3+, system prompt + tool definitions + early conversation history are read from cache at 10x discount.

Minimum prompt: 1024–4096 tokens depending on model (Anthropic silently skips caching for shorter prompts — no error, no extra charge).

Provider guard: only adds cache_control when payload.model starts with "claude-". OpenAI, Google, and other providers are passed through unchanged.

Files

pi-airgun/
├── package.json
├── README.md
├── vitest.config.ts
├── tsconfig.json
├── tests/
│   ├── pipeline.test.ts          runImmediatePipeline / runDeferredPipeline integration
│   ├── stages/
│   │   ├── ansi.test.ts
│   │   ├── whitespace.test.ts
│   │   ├── dedup.test.ts
│   │   ├── separator.test.ts
│   │   ├── paths.test.ts
│   │   ├── toon.test.ts
│   │   ├── tokens.test.ts
│   │   └── tokens_dyn.test.ts
│   └── bench/
│       ├── stages.bench.ts       Per-stage microbenchmarks
│       └── pipeline.bench.ts     Full pipeline benchmarks + cache effectiveness
└── extensions/
    ├── compress/
    │   ├── index.ts              Extension entry: session_start / tool_result / context hooks + /compress-stats
    │   ├── pipeline.ts           runImmediatePipeline() + runDeferredPipeline()
    │   └── stages/
    │       ├── ansi.ts           node:util.stripVTControlCharacters wrapper
    │       ├── whitespace.ts     Normalize blank lines and trailing spaces
    │       ├── dedup.ts          Consecutive duplicate line folding
    │       ├── separator.ts      Separator line normalizer
    │       ├── paths.ts          Path → $WS/$HOME sigil compression
    │       ├── toon.ts           JSON → TOON encoding via @toon-format/toon
    │       ├── tokens.ts         js-tiktoken wrapper + fast ÷3.5 estimator
    │       └── tokens_dyn.ts     Dynamic repeated-token compressor
    └── cache/
        └── index.ts              before_provider_request → add Anthropic cache_control

Development

# Install dependencies
npm install

# Run tests
npm test

# Run benchmarks
npm run bench

# Type check
npm run typecheck

Ideas for future stages

• Log timestamp folding: group log lines by repeating prefix, show count + time range
• Import block dedup: for code file reads, deduplicate repeated import sections
• Cross-message dedup: if the same file is read twice, replace the second with a back-reference
• 1-hour cache TTL: add ttl: { type: "hours", amount: 1 } to cache_control for long sessions