Creating snip Filters

You are an expert at writing declarative YAML filters for snip, a CLI proxy that reduces LLM token consumption by filtering shell output.

Filter File Location

• Built-in filters: filters/*.yaml (embedded in the binary at build time)
• User filters: ~/.config/snip/filters/*.yaml (override built-in filters by name)
• Per-project filters: configure additional directories via filters.dir array in ~/.config/snip/config.toml (e.g. dir = ["~/.config/snip/filters", "${env.PWD}/.snip"]). Later directories take priority.

Trust store: filters in any directory outside ~/.config/snip/ are ignored (with a stderr warning) until approved once with snip trust <dir>, which pins each file's SHA-256. Re-run snip trust after editing a trusted file.

Filter Structure

Every filter is a YAML file with this structure:

name: "tool-subcommand"          # Required. Unique identifier, used for registry lookup.
version: 1                       # Informational revision number of the filter (bump on behavior change).
description: "What this filter does"  # Human-readable purpose.

match:                           # Required. When to apply this filter.
  command: "tool"                # Required. The CLI tool name (e.g., "git", "go", "npm").
  subcommand: "sub"             # Optional. First non-flag argument (e.g., "test", "log").
                                # Also accepts a list: ["install", "add", "i"]; include ""
                                # in the list to match the bare command invocation too.
  exclude_flags: ["-v", "--json"]  # Optional. Skip filter if user passes any of these.
  require_flags: ["--all"]      # Optional. Only apply if user passes ALL of these.

inject:                          # Optional. Modify command args before execution.
  args: ["--json"]              # Arguments to append to the command.
  defaults:                     # Flag defaults, only added if flag not already present.
    "-n": "10"
  skip_if_present: ["--json"]   # Don't inject anything if any of these flags are present.

streams: ["stdout", "stderr"]    # Optional. Which streams to filter. Default: ["stdout"].
                                 # Use ["stderr"] for tools that output to stderr (e.g., bun test).
                                 # Use ["stdout", "stderr"] to filter both streams merged together.

pipeline:                        # Required. Ordered list of transformation actions.
  - action: "keep_lines"
    pattern: "\\S"
  - action: "head"
    n: 20

on_error: "passthrough"          # Descriptive convention: the engine ALWAYS falls back to raw
                                 # output when a pipeline fails; no other value is implemented.

Match Rules

• command is matched exactly against the first token of the shell command.
• subcommand is matched against the first non-flag argument.
• Flag matching uses prefix matching: "-v" matches both -v and -verbose.
• Registry lookup is O(1) by key "command" or "command:subcommand".

Inject Behavior

• Injected args are inserted before any -- separator, otherwise appended.
• defaults only apply if their flag key is not already present in the user's args.
• If any flag in skip_if_present is found, the entire inject block is skipped.

The 20 Pipeline Actions

Line Filtering

Line Transformation

Extraction & Grouping

JSON Processing

Formatting & Conditionals

Template Data for format_template

The template receives:

• {{.lines}} - all current lines joined with newlines
• {{.count}} - number of lines
• {{.groups}} - map from group_by action (if used earlier in pipeline)
• {{.stats}} - map from aggregate action (if used earlier in pipeline)

{{.count}} trap: it counts the lines reaching the template, not entities. After any stage that emits a summary, an overflow marker or a cap, the number is wrong (caused bug #125). Prefer the tool's own count over recomputing one.

Metadata Flow Between Actions

• group_by sets metadata "groups" (map[string]int)
• aggregate sets metadata "stats" (map[string]int)
• format_template can access both via {{.groups}} and {{.stats}}
• All other actions pass metadata through unchanged

Design Principles

1. Start with keep_lines pattern "\\S" to strip blank lines early.
2. Use inject to request machine-readable output (e.g., --json, --porcelain) then filter that structured data.
3. Respect user intent: use exclude_flags to skip filtering when the user explicitly requests a different format.
4. Keep the conventional on_error: "passthrough" line: it documents the engine's actual fallback behavior (raw output on any pipeline failure).
5. Chain actions from broad to specific: filter noise first, then extract, then format.
6. Keep output minimal but useful: the goal is 60-90% token reduction while preserving actionable information.

Examples

Simple: remove noise lines

name: "npm-install"
version: 1
description: "Condensed npm install output"
match:
  command: "npm"
  subcommand: "install"
pipeline:
  - action: "remove_lines"
    pattern: "^(npm warn|npm notice)"
  - action: "keep_lines"
    pattern: "\\S"
  - action: "aggregate"
    patterns:
      added: "^added "
      removed: "^removed "
      up_to_date: "up to date"
    format: "{{if gt .up_to_date 0}}up to date{{else}}{{.added}} added, {{.removed}} removed{{end}}"
on_error: "passthrough"

Intermediate: inject flags + extract structured data

name: "go-test"
version: 1
description: "Condensed go test output with pass/fail summary"
match:
  command: "go"
  subcommand: "test"
  exclude_flags: ["-json", "-v", "-bench", "-run"]
inject:
  args: ["-json"]
  skip_if_present: ["-json", "-v", "-bench"]
pipeline:
  - action: "keep_lines"
    pattern: "\\S"
  - action: "keep_lines"
    pattern: "\"Test\":\""
  - action: "keep_lines"
    pattern: "\"Action\":\"(pass|fail)\""
  - action: "aggregate"
    patterns:
      passed: '"Action":"pass"'
      failed: '"Action":"fail"'
    format: "{{if and (eq .passed 0) (eq .failed 0)}}No tests found{{else}}{{.passed}} passed, {{.failed}} failed{{end}}"
on_error: "passthrough"

Advanced: state machine for multi-section output

name: "cargo-test"
version: 2
description: "cargo test summary lines, plus the failure report when a test fails"
match:
  command: "cargo"
  subcommand: "test"
pipeline:
  - action: "remove_lines"
    pattern: "^\\s*(Compiling|Downloading|Downloaded|Updating|Running|Executable)"
  - action: "keep_lines"
    pattern: "\\S"
  - action: "state_machine"
    states:
      start:
        keep: "^test result"
        until: "^failures"
        next: "failures"
      failures:
        keep: "."
  - action: "head"
    n: 150
  - action: "format_template"
    template: "{{.lines}}"
on_error: "passthrough"

The until on start is what makes this safe. Everything after the first failures: line is the failure report, and a panic message can hold any text at all — including a line that looks exactly like a test result. So every stage that drops or counts lines has to sit on the start side of that boundary, which keep does. A remove_lines placed after the state machine would instead run over the panic messages and delete them.

Workflow to Create a New Filter

1. Identify the command and its typical verbose output.
2. Run the command and capture raw output to understand the structure.
3. Decide what to keep: what information does the LLM actually need?
4. Check if the tool has a machine-readable flag (--json, --porcelain, etc.) that would make filtering easier -- use inject if so.
5. Write the pipeline: strip blanks, filter/extract, aggregate, format.
6. Test the filter by placing it in ~/.config/snip/filters/ and running the command through snip.
7. To contribute: add the YAML to filters/ in the repo and submit a PR.

snip - Reduce LLM Token Usage by 60-90%

CLI proxy that filters shell output before it reaches your AI coding assistant's context window. Works with Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Cline, Codex, Pi, Grok Build, Kilo Code, Antigravity, OpenCode, OpenClaw, Aider, and any tool that runs shell commands.

AI coding agents burn tokens on verbose shell output that adds zero signal. A passing go test produces hundreds of lines the LLM will never use. git log dumps full commit metadata when a one-liner per commit suffices.

snip sits between your AI tool and the shell, filtering output through declarative YAML pipelines. Write a YAML file, drop it in a folder, done. The extensible LLM token optimizer: filters are YAML data files, not compiled code.

  snip — Token Savings Report
  ══════════════════════════════

  Commands filtered     128
  Tokens saved          2.3M
  Avg savings           99.8%
  Efficiency            Elite
  Total time            725.9s

  ███████████████████░ 100%

  14-day trend  ▁█▇

  Top commands by tokens saved

  Command                    Runs  Saved   Savings  Impact
  ─────────────────────────  ────  ──────  ───────  ────────────
  go test ./...              8     806.2K  99.8%    ████████████
  go test ./pkg/...          3     482.9K  99.8%    ███████░░░░░
  go test ./... -count=1     3     482.0K  99.8%    ███████░░░░░

Measured on a real Claude Code session — 128 commands, 2.3M tokens saved.

Quick Start

# Quick install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/edouard-claude/snip/master/install.sh | sh

# Or via Homebrew
brew install edouard-claude/tap/snip

# Or with Go
go install github.com/edouard-claude/snip/cmd/snip@latest

# Then hook into Claude Code
snip init
# That's it. Every shell command Claude runs now goes through snip.

How It Works

Before — Claude Code sees this (275 tokens):

$ go test ./...
ok  	github.com/edouard-claude/snip	13.697s
?   	github.com/edouard-claude/snip/cmd/snip	[no test files]
ok  	github.com/edouard-claude/snip/internal/cli	1.357s
ok  	github.com/edouard-claude/snip/internal/config	1.898s
ok  	github.com/edouard-claude/snip/internal/discover	4.271s
ok  	github.com/edouard-claude/snip/internal/display	2.516s
ok  	github.com/edouard-claude/snip/internal/economics	3.073s
ok  	github.com/edouard-claude/snip/internal/engine	5.262s
ok  	github.com/edouard-claude/snip/internal/filter	3.687s
ok  	github.com/edouard-claude/snip/internal/hook	4.555s
ok  	github.com/edouard-claude/snip/internal/hookaudit	4.560s
ok  	github.com/edouard-claude/snip/internal/initcmd	4.534s
ok  	github.com/edouard-claude/snip/internal/inspect	4.598s
ok  	github.com/edouard-claude/snip/internal/learn	4.474s
ok  	github.com/edouard-claude/snip/internal/tee	4.430s
ok  	github.com/edouard-claude/snip/internal/tracking	4.055s
ok  	github.com/edouard-claude/snip/internal/trust	4.544s
ok  	github.com/edouard-claude/snip/internal/utils	4.528s
ok  	github.com/edouard-claude/snip/internal/verify	4.517s

After — snip returns this (8 tokens):

1125 passed, 0 failed

That's 97% fewer tokens, measured on this very repository. The filter injects -json and counts individual test results, so the LLM gets more signal — 1125 tests passed, not just 18 packages — in a fraction of the space.

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐     ┌────────────┐
│ Claude Code │────>│ snip intercept  │────>│ run command  │────>│   filter   │
│  runs git   │     │  match filter   │     │  capture I/O │     │  pipeline  │
└─────────────┘     └─────────────────┘     └──────────────┘     └─────┬──────┘
                                                                       │
                    ┌─────────────────┐     ┌──────────────┐           │
                    │   Claude Code   │<────│ track savings│<──────────┘
                    │  sees filtered  │     │  in SQLite   │
                    └─────────────────┘     └──────────────┘

No filter match? The command passes through unchanged — zero overhead.

Token Savings by Command

Stop wasting tokens on noise. snip gives the LLM the same signal in a fraction of the context window.

Installation

Homebrew (recommended)

brew install edouard-claude/tap/snip

From GitHub Releases

Download the latest binary for your platform from Releases.

# macOS (Apple Silicon)
curl -Lo snip.tar.gz https://github.com/edouard-claude/snip/releases/latest/download/snip_$(curl -s https://api.github.com/repos/edouard-claude/snip/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)_darwin_arm64.tar.gz
tar xzf snip.tar.gz && mv snip /usr/local/bin/

From source

go install github.com/edouard-claude/snip/cmd/snip@latest

Or build locally:

git clone https://github.com/edouard-claude/snip.git
cd snip && make install

make install and make install-lite use the first available destination: an explicit GOBIN, go env GOBIN, or the first go env GOPATH entry plus /bin. Use make upgrade or make upgrade-lite to replace the resolved snip on PATH instead. An explicit GOBIN overrides the upgrade destination.

Requires Go 1.25+.

Supported AI Tools

snip integrates with every major AI coding assistant. One binary, universal compatibility.

Claude Code

snip init

This installs a PreToolUse hook that transparently rewrites supported commands. Claude Code never sees the substitution -- it receives compressed output as if the original command produced it.

Supported commands: 132 filters covering 100 distinct commands: git, go, cargo, npm, yarn, pnpm, docker, kubectl, terraform, aws, gh, dotnet, and many more.

snip init --uninstall   # remove the hook

Cursor

snip init --agent cursor

This patches ~/.cursor/hooks.json with a beforeShellExecution hook. Works the same way as Claude Code.

snip init --agent cursor --uninstall   # remove the hook

Pi (pi.dev)

snip init --agent pi

This patches ~/.pi/agent/settings.json with a PreToolUse entry matching the bash tool. The runtime hook is interpreted by the community extension @hsingjui/pi-hooks, which mirrors Claude Code's hookSpecificOutput format (including command rewriting via updatedInput). Install it once:

pi install npm:@hsingjui/pi-hooks

Then run /reload (or restart Pi). Once active, snip rewrites supported commands transparently.

snip init --agent pi --uninstall   # remove the hook

Grok Build (xAI)

snip init --agent grok

This writes ~/.grok/hooks/snip.json with a PreToolUse hook matching the shell tool. Grok Build hooks cannot rewrite commands in place (the hook contract is allow/deny only), so snip denies matched commands with a re-run suggestion ("…/snip" run -- <command>). Non-matching commands pass through untouched, and the hook is fail-open: if snip breaks, commands simply run unfiltered.

Prefer prompt injection instead? Grok Build reads AGENTS.md natively:

snip init --agent grok --mode prompt   # creates AGENTS.md
snip init --agent grok --uninstall     # remove the hook

AGENTS.md is shared with Codex, so --uninstall never deletes it; it prints a reminder instead.

Codex

snip init --agent codex

This patches ~/.codex/hooks.json with a native PreToolUse hook. Supported shell commands are transparently rewritten through snip with Codex's updatedInput contract, so the model runs commands normally and sees only the filtered output.

For safety, mixed commands containing unsupported segments, pipelines with uninspected tails, and command substitutions pass through unchanged so Codex keeps its native permission flow.

Use `sni