PandaFilter

The context intelligence layer for AI coding agents.

The layer between your tools and your AI. PandaFilter understands what's noise and what matters — compressing, routing, and preserving the right context so your agent thinks faster, costs less, and never loses its place.

Install

brew tap AssafWoo/pandafilter
brew install pandafilter

Linux / any platform:

curl -fsSL https://raw.githubusercontent.com/AssafWoo/homebrew-pandafilter/main/install.sh | bash

First run: PandaFilter downloads the BERT model (~90 MB, all-MiniLM-L6-v2) from HuggingFace and caches it at ~/.cache/huggingface/. Subsequent runs are instant.

Then wire it in — one command installs for every AI agent you have:

panda init --agent all

Auto-detects Claude Code, Cursor, Gemini CLI, Codex, Windsurf, Cline, OpenClaw, and VS Code Copilot. Skips anything that isn't installed. Or target one specifically:

panda init                          # Claude Code (default)
panda init --agent cursor           # Cursor
panda init --agent gemini           # Gemini CLI
panda init --agent codex            # Codex (CLI + VS Code extension)
panda init --agent windsurf         # Windsurf
panda init --agent cline            # Cline
panda init --agent openclaw         # OpenClaw
panda init --agent copilot          # VS Code Copilot

What PandaFilter Does

1. Intelligent Compression

Raw command output is filtered, deduplicated, and semantically compressed by a BERT-powered pipeline that understands what matters for your task — not just what matches a regex. When your AI agent runs pip install, cargo build, or npm install, PandaFilter intercepts the output and strips download progress, module graphs, and passing test lines. The agent sees a clean summary with errors, warnings, and results. Nothing useful is dropped.

2. Adaptive Routing (new in v1.3.0)

A content-aware router analyzes each output and activates only the strategies relevant to it: error-focus for test failures, dedup for log streams, structural digest for unchanged file re-reads, semantic summarization for prose. No more one-size-fits-all.

Enable with use_router = true in panda.toml.

3. Session Intelligence

PandaFilter learns your codebase's noise patterns across sessions. It tracks what you've read, what you've changed, and where the context pressure is building — adapting its compression strategy in real time.

New in v1.3.0: File re-reads now send diffs instead of full file content. Unchanged re-reads return structural digests (function/class signatures). Both happen automatically — no config needed.

4. Compaction Survival (new in v1.3.0)

When your agent's context fills up and auto-compacts, PandaFilter preserves what matters: edited files, error signatures, key decisions. The next session starts oriented, not blank.

Requires Claude Code and is installed automatically with panda init.

How it works

When your AI agent runs a command — pip install, cargo build, npm install — PandaFilter intercepts the output and removes everything the model doesn't need: download progress, module graphs, passing test lines, spinners. The agent sees a clean summary with errors, warnings, and results. Nothing useful is dropped.

No config changes. No workflow changes. Runs 100% locally.

See it in action

Run panda gain after a session to see your cumulative savings:

Token savings

Numbers from ccr/tests/handler_benchmarks.rs. Run panda gain to see your own live data.

What's new in v1.3.0

Commands

panda gain — see your token savings:

panda gain                    # overall summary
panda gain --breakdown        # per-command table
panda gain --history          # last 14 days
panda gain --insight          # categorized savings + top saves

panda doctor — diagnose the full installation in one command.

panda init --uninstall — remove hooks:

panda init --uninstall                  # Claude Code
panda init --agent cursor --uninstall   # Cursor

panda focus — opt-in: tells the agent which files matter for the current prompt, preventing unnecessary reads:

panda focus --enable             # enable for this repo
panda focus --disable            # disable (keeps index data)
panda focus --status             # show status + index age
panda focus --dry-run            # preview guidance without enabling

panda index — manually rebuild the file-relationship index:

panda index                      # full/incremental build for current repo

Other commands:

panda verify                            # check hook integrity
panda discover                          # scan history for unfiltered commands
panda run git status                    # run a command through PandaFilter manually
panda proxy git status                  # run raw (no filtering), record baseline
panda read-file src/main.rs --level auto  # preview read filtering
panda expand ZI_3                       # restore a collapsed block
panda noise                             # show learned noise patterns; --reset to clear
panda compress --scan-session           # compress current conversation context

0. Hard input ceiling (200k chars — truncates before any stage)
1. Strip ANSI codes
2. Normalize whitespace
3. Global regex pre-filter (progress bars, spinners, download lines, decorators)
4. NDJSON streaming compaction (go test -json, jest JSON reporter)
5. Command-specific pattern filter
6. If over summarize_threshold_lines:
   6a. BERT noise pre-filter
   6b. Entropy-adaptive BERT summarization (up to 7 passes)
7. Hard output cap (50k chars)

[global]
summarize_threshold_lines = 50
head_lines = 30
tail_lines = 30
strip_ansi = true
normalize_whitespace = true
deduplicate_lines = true
input_char_ceiling = 200000
output_char_cap = 50000
# cost_per_million_tokens = 15.0

# v1.3.0: Adaptive MoE router (opt-in)
# use_router = true                  # enable adaptive expert routing
# router_exploration_noise = true    # prevent expert collapse in long sessions

[tee]
enabled = true
mode = "aggressive"   # "aggressive" | "always" | "never"

[read]
mode = "auto"   # "passthrough" | "auto" | "strip" | "aggressive" | "structural"
# v1.3.0: delta mode (re-reads send diffs) and structural mode (signature-only) are
# now active automatically — no config change needed.

[focus]
enabled = false       # disabled by default — enable with `panda focus --enable` after testing
min_files = 25        # skip for repos smaller than this
min_lines = 2000      # skip for repos with fewer source lines

[commands.git]
patterns = [
  { regex = "^(Counting|Compressing|Receiving|Resolving) objects:.*", action = "Remove" },
]

[commands.cargo]
patterns = [
  { regex = "^\\s+Compiling \\S+ v[\\d.]+", action = "Collapse" },
  { regex = "^\\s+Downloaded \\S+ v[\\d.]+", action = "Remove"   },
]

[commands.myapp]
patterns = [
  { regex = "^DEBUG:",            action = "Remove" },
  { regex = "^\\S+\\.ts\\(",     action = "TruncateLinesAt", max_chars = 120 },
]
on_empty = "(no relevant output)"

[commands.myapp.match_output]
pattern        = "Server started"
message        = "ok — server ready"
unless_pattern = "error"

ccr/        CLI binary (panda) — handlers, hooks, session state, commands
ccr-core/   Core library (no I/O) — pipeline, BERT summarizer, config, analytics
ccr-sdk/    Conversation compression — tiered compressor, deduplicator, Ollama
ccr-eval/   Evaluation suite — fixtures against Claude API
config/     Embedded default filter patterns

panda init --uninstall                            # Claude Code
panda init --agent cursor   --uninstall           # Cursor
panda init --agent gemini   --uninstall           # Gemini CLI
panda init --agent codex    --uninstall           # Codex
panda init --agent windsurf --uninstall           # Windsurf
panda init --agent cline    --uninstall           # Cline
panda init --agent copilot  --uninstall           # VS Code Copilot

brew uninstall pandafilter && brew untap AssafWoo/pandafilter   # Homebrew
# or: cargo uninstall panda

rm -rf ~/.local/share/panda                   # analytics + sessions
rm -rf ~/.cache/huggingface/hub/models--sentence-transformers--all-MiniLM-L6-v2

FAQ

Does PandaFilter change what the agent can see? It removes noise — build progress, passing test lines, module download logs. Errors, file paths, and results are always kept.

What if I don't want a specific command filtered? Add a rule to .panda/filters.toml to customize or override any handler. See the User-defined filters section. You can also use panda proxy <cmd> to run a command raw with no filtering.

What about commands PandaFilter doesn't know? Output passes through unchanged. PandaFilter never silently drops output from unknown commands.

How do I verify it's working? Run panda gain after a session. To see exactly what the agent received from a specific command: panda run git log --oneline -20.

Does PandaFilter send any data outside my machine? No. All processing is fully local. BERT runs on-device.

What is Context Focusing? An opt-in feature that tells the agent which files are relevant for the current prompt, preventing it from reading unrelated files. Enable with panda focus --enable after running panda doctor to confirm the index is ready.

Why PandaFilter? Why Panda?

AI coding sessions are expensive — not because of what you ask, but because of what the agent reads back. Every cargo build or npm install dumps thousands of tokens of noise into the context window. I built PandaFilter to strip that out automatically.

The name comes from how a panda eats: it consumes enormous amounts of raw material and extracts only what it needs.

— Assaf Petronio · github.com/AssafWoo

Contributing

Open an issue or PR on GitHub. To add a handler: implement the Handler trait and register it in ccr/src/handlers/mod.rs — see git.rs as a template.

License

MIT — see LICENSE.