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.

$ 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.24+ and jq (for the hook script).

Supported AI Tools

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

| Tool | Install | Method | |------|---------|--------| | Claude Code | snip init | PreToolUse hook | | Cursor | hooks.json config | beforeShellExecution hook | | OpenCode | opencode-snip plugin | tool.execute.before hook | | GitHub Copilot | shell aliases | prefix commands with snip | | Gemini CLI | shell aliases | prefix commands with snip | | Codex (OpenAI) | shell aliases | prefix commands with snip | | Windsurf | shell aliases | prefix commands with snip | | Cline / Roo Code | shell aliases | prefix commands with snip | | 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: git, go, cargo, npm, npx, yarn, pnpm, docker, kubectl, make, pip, pytest, jest, tsc, eslint, rustc.

snip init --uninstall   # remove the hook

Cursor

Cursor supports hooks since v1.7 via ~/.cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": "~/.claude/hooks/snip-rewrite.sh" }
    ]
  }
}

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.

Copilot / Gemini / Codex / Windsurf / Cline / 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 --json            # machine-readable output
snip gain --csv             # CSV export
snip -v <command>           # verbose mode (show filter details)
snip proxy <command>        # force passthrough (no filtering)
snip config                 # show config
snip init                   # install Claude Code hook
snip init --uninstall       # remove hook

Filters

Filters are declarative YAML files. The binary is the engine, filters are data — the two evolve independently.

name: "git-log"
version: 1
description: "Condense git log to hash + message"

match:
  command: "git"
  subcommand: "log"
  exclude_flags: ["--format", "--pretty", "--oneline"]

inject:
  args: ["--pretty=format:%h %s (%ar) <%an>", "--no-merges"]
  defaults:
    "-n": "10"

pipeline:
  - action: "keep_lines"
    pattern: "\\S"
  - action: "truncate_lines"
    max: 80
  - action: "format_template"
    template: "{{.count}} commits:\n{{.lines}}"

on_error: "passthrough"

Built-in Filters

| Filter | What it does | |--------|-------------| | git-status | Categorized status with file counts | | git-diff | Stat summary, truncated to 30 files | | git-log | One-line per commit: hash + message + author + date | | go-test | Pass/fail summary with failure details | | cargo-test | Pass/fail summary with failure details |

16 Pipeline Actions

| Action | Description | |--------|-------------| | keep_lines | Keep lines matching regex | | remove_lines | Remove lines matching regex | | truncate_lines | Truncate lines to max length | | strip_ansi | Remove ANSI escape codes | | head / tail | Keep first/last N lines | | group_by | Group lines by regex capture | | dedup | Deduplicate with optional normalization | | json_extract | Extract fields from JSON | | json_schema | Infer schema from JSON | | ndjson_stream | Process newline-delimited JSON | | regex_extract | Extract regex captures | | state_machine | Multi-state line processing | | aggregate | Count p