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 16 Pipeline Actions

Line Filtering

| Action | Params | Description | |--------|--------|-------------| | keep_lines | pattern (regex) | Keep only lines matching the pattern | | remove_lines | pattern (regex) | Remove lines matching the pattern | | head | n (int, default 10), overflow_msg (string, default "+{remaining} more lines") | Keep first N lines | | tail | n (int, default 10) | Keep last N lines | | dedup | normalize ([]string of regexes to strip before comparing), top (int, 0=all) | Deduplicate lines, output "text (xN)" for repeats |

Line Transformation

| Action | Params | Description | |--------|--------|-------------| | truncate_lines | max (int, default 80), ellipsis (string, default "...") | Truncate long lines | | strip_ansi | (none) | Remove ANSI escape codes | | compact_path | (none) | Remove directory prefixes from file paths |

Extraction & Grouping

| Action | Params | Description | |--------|--------|-------------| | regex_extract | pattern (regex with capture groups), format (string using $0, $1, $2...) | Extract data via regex capture groups | | group_by | pattern (regex with capture group), format (template, default "{{.Key}}: {{.Count}}"), top (int) | Group lines by capture group, count occurrences | | aggregate | patterns (map of name->regex), format (Go template) | Count matches for named patterns across all input | | state_machine | states (map of state definitions with keep, until, next) | Stateful line filtering with transitions |

JSON Processing

| Action | Params | Description | |--------|--------|-------------| | json_extract | fields ([]string), format (template, optional) | Extract fields from JSON input | | json_schema | max_depth (int, default 3) | Output JSON type schema | | ndjson_stream | group_by (string field name), format (template with .Key, .Count, .Events) | Process newline-delimited JSON |

Formatting

| Action | Params | Description | |--------|--------|-------------| | format_template | template (Go text/template, required) | Format output using Go template |

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)

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. Always set on_error: "passthrough" so raw output is returned if filtering fails.
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: 1
description: "Condensed cargo test output"
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 |running |test result)"
        until: "^failures"
        next: "failures"
      failures:
        keep: "."
        until: "^$"
        next: "done"
  - action: "aggregate"
    patterns:
      pass: "\\.\\.\\. ok$"
      fail: "\\.\\.\\. FAILED$"
      ignored: "\\.\\.\\. ignored$"
  - action: "format_template"
    template: "{{.lines}}"
on_error: "passthrough"

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.

How It Works

Before — Claude Code sees this (689 tokens):

$ go test ./...
ok  	github.com/edouard-claude/snip/internal/cli	3.728s	coverage: 14.4% of statements
ok  	github.com/edouard-claude/snip/internal/config	2.359s	coverage: 65.0% of statements
ok  	github.com/edouard-claude/snip/internal/display	1.221s	coverage: 72.6% of statements
ok  	github.com/edouard-claude/snip/internal/engine	1.816s	coverage: 47.9% of statements
ok  	github.com/edouard-claude/snip/internal/filter	4.306s	coverage: 72.3% of statements
ok  	github.com/edouard-claude/snip/internal/initcmd	2.981s	coverage: 59.1% of statements
ok  	github.com/edouard-claude/snip/internal/tee	0.614s	coverage: 70.6% of statements
ok  	github.com/edouard-claude/snip/internal/tracking	5.355s	coverage: 75.0% of statements
ok  	github.com/edouard-claude/snip/internal/utils	5.515s	coverage: 100.0% of statements

After — snip returns this (16 tokens):

10 passed, 0 failed

That's 97.7% fewer tokens. The LLM gets the same signal — all tests pass — without the noise.

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐     ┌────────────┐
│ 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

| Command | Before | After | Reduction | |---------|-------:|------:|----------:| | cargo test | 591 tokens | 5 tokens | 99.2% | | go test ./... | 689 tokens | 16 tokens | 97.7% | | git log | 371 tokens | 53 tokens | 85.7% | | git status | 112 tokens | 16 tokens | 85.7% | | git diff | 355 tokens | 66 tokens | 81.4% |

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

Requires Go 1.25+.

Supported AI Tools

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

| Tool | Install | Method | |------|---------|--------| | Claude Code | snip init | PreToolUse hook (native) | | Cursor | snip init --agent cursor | beforeShellExecution hook (native) | | GitHub Copilot | snip init --agent copilot | .github/copilot-instructions.md | | Gemini CLI | snip init --agent gemini | GEMINI.md prompt injection | | Codex (OpenAI) | snip init --agent codex | AGENTS.md prompt injection | | Pi (pi.dev) | snip init --agent pi | PreToolUse hook (via pi-hooks) | | Windsurf | snip init --agent windsurf | .windsurfrules prompt injection | | Cline / Roo Code | snip init --agent cline | .clinerules prompt injection | | Kilo Code | snip init --agent kilocode | .kilocode/rules/ prompt injection | | Antigravity | snip init --agent antigravity | .agents/rules/ prompt injection | | OpenCode | opencode-snip plugin | tool.execute.before hook | | OpenClaw | openclaw plugins install openclaw-snip | plugin | | Aider | shell aliases | prefix commands with snip |

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: 127 filters covering git, go, cargo, npm, yarn, pnpm, docker, kubectl, terraform, aws, gh, and 80+ more tools.

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

Copilot / Gemini / Codex / Windsurf / Cline / Kilo Code / Antigravity

snip init --agent copilot      # creates .github/copilot-instructions.md
snip init --agent gemini       # creates GEMINI.md
snip init --agent codex        # creates AGENTS.md
snip init --agent windsurf     # creates .windsurfrules
snip init --agent cline        # creates .clinerules
snip init --agent kilocode     # creates .kilocode/rules/snip-rules.md
snip init --agent antigravity  # creates .agents/rules/snip-rules.md

These agents use prompt injection: a markdown file instructs the LLM to prefix shell commands with snip. Project-scoped (created in the current directory).

OpenCode

Install the opencode-snip plugin by adding it to your OpenCode config (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-snip@latest"]
}

The plugin uses the tool.execute.before hook to automatically prefix all commands with snip. Commands not supported by snip pass through unchanged.

OpenClaw

openclaw plugins install openclaw-snip

Aider

Use shell aliases to route commands through snip:

# Add to ~/.bashrc or ~/.zshrc
alias git="snip git"
alias go="snip go"
alias cargo="snip cargo"

Or instruct the LLM via system prompt to prefix commands with snip.

Standalone

snip works without any AI tool:

snip git log -10
snip go test ./...
snip gain             # token savings report

Usage

snip <command> [args]       # filter a command
snip gain                   # full dashboard (summary + sparkline + top commands)
snip gain --daily           # daily breakdown
snip gain --weekly          # weekly breakdown
snip gain --monthly         # monthly breakdown
snip gain --top 10          # top N commands by tokens saved
snip gain --history 20      # last 20 commands
snip gain --no-truncate     # disable command truncation
snip gain --json            # machine-readable output
snip gain --csv             # CSV export
snip discover               # find