instant-grep

The AI agent's search engine. Trigram-indexed regex, token-compressed git, sub-ms daemon.

Benchmarks · Installation · Token Savings · Agent Integration · How it works

brew install MakFly/tap/ig

One binary. 4MB. Zero dependencies. ig replaces grep, cat, ls, tree, find, and git status/log/diff with token-optimized alternatives — built for AI coding agents (Claude Code, Codex, OpenCode, Cursor).

$ ig "async fn.*Result" src/ --stats

src/daemon.rs
23:    pub async fn handle_connection(stream: UnixStream) -> Result<()> {

--- stats ---
Candidates: 4/1284 files (0.3%)
Search: 1.5ms
Index: yes

The numbers (measured, not estimated)

Every number on this page is measured with wc -c on real commands, on real projects (1,609-file Laravel app, 3,084-file monorepo). See the interactive benchmark dashboard for charts.

Why

AI agents call CLI tools constantly. Every byte of output is a token consumed. On a $200/month Claude Code Max plan, wasted tokens = hitting rate limits sooner.

ig solves this at two levels:

1. Search — trigram-indexed regex search (same algorithm as GitHub Code Search). First search auto-builds the index. Subsequent searches: near-instant.

2. Token compression — ig git status outputs 25 bytes instead of 422. ig read adds line numbers. ig ls produces compact listings. A PreToolUse hook rewrites commands transparently — the AI agent never knows the difference.

Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/MakFly/instant-grep/main/install.sh | bash

Installs the binary and runs ig setup to configure all detected AI agents.

Homebrew

brew install MakFly/tap/ig

Download binary

Grab the latest from Releases:

Build from source

git clone https://github.com/MakFly/instant-grep.git
cd instant-grep
cargo build --release
cp target/release/ig ~/.local/bin/

Token Savings

Git proxy — measured compression

ig git replaces verbose git output with compact summaries. The hook rewrites git status → ig git status transparently.

Cumulative savings (real session, 800+ commands)

Total input:     7.2 MB (native command output)
Total output:    1.7 MB (ig compressed output)
Bytes saved:     5.5 MB (76%)
Tokens saved:    ~1,377,000 tokens

Impact on Claude Code Opus 4.6 session

On a Max 20x plan ($200/month), this means 40-60% more messages before hitting rate limits.

Token analytics

ig gain                       # savings dashboard
ig gain --history             # individual command history
ig gain --json                # machine-readable output
ig discover                   # find missed optimization opportunities

Deny/Ask safety rules

ig rewrite protects against destructive commands:

Usage

Search

ig "pattern" .                    # auto-indexes on first run
ig -i "todo|fixme" .              # case-insensitive
ig "useRouter" . --type ts        # filter by file type
ig -C 3 "async fn" src/           # context lines
ig "fetchData" . --json           # JSON output for agents
ig "Result<T>" . --stats          # show performance stats

File intelligence

ig read src/main.rs               # numbered lines
ig read src/main.rs -s            # signatures only (imports + function names, -87%)
ig read src/main.rs -a            # aggressive mode (strip comments, elide bodies)
ig read src/main.rs -b 500        # budget mode (500 tokens max, entropy-scored)
ig read src/main.rs -r "payment"  # relevance boost (keep payment-related code)
ig read src/main.rs -d            # delta mode (git-changed lines only)
ig smart .                        # 2-line summary per file
ig symbols .                      # all function/class definitions
ig context src/main.rs 42         # enclosing code block at line 42
ig ls                             # compact directory listing (-65%)
ig pack                           # generate .ig/context.md (full project map)
ig files .                        # list all files (respects .gitignore)
ig files --compact                # tree-compressed listing (÷300 vs raw)

Git proxy

ig git status                     # compact porcelain output (-94%)
ig git log                        # oneline + stats, 10 max (-89%)
ig git diff                       # stat first, then truncated diff (-74%)
ig git show HEAD                  # stat + compact diff (-51%)
ig git branch -a                  # passthrough (already compact)

Daemon mode (sub-millisecond)

ig daemon start .                 # persistent search process
ig query "pattern" .              # 0.2ms response via Unix socket
ig daemon stop .
ig daemon install .               # auto-restart on macOS reboot

Index management

ig index .                        # build or rebuild
ig status .                       # show stats
ig watch .                        # auto-rebuild on file changes

Agent Integration

One-shot setup

ig setup                          # configure all detected agents
ig setup --dry-run                # preview without writing

ig setup detects and configures every installed agent automatically:

Claude Code hooks installed:

• ig-rewrite.sh — transparent command rewriting
• prefer-ig.sh — blocks rg/grep -r/find in favor of ig
• session-start.sh — version change detection + token savings summary
• format.sh — auto-format on file writes
• Grep tool blocker, npm/npx blocker, destructive git blocker, secret detection, .env warning
• SubagentStart context injection (every subagent receives ig instructions)
• TaskCompleted quality gate (runs tests before marking done)

100% idempotent. Safe to run multiple times. --dry-run to preview.

For AI agent developers

ig follows the CLI > MCP consensus:

• 35x fewer tokens than MCP (4K vs 145K for equivalent tool schemas)
• Zero config — just ig --json via Bash
• LLMs already know CLIs — trained on millions of man pages
• Composable — pipe to jq, head, wc

Since v1.6.23, ig is a complete standalone solution for AI agent token optimization. No additional tools needed.

Benchmarks

Real projects (measured on Apple M4 Max, macOS 15.5)

ig v1.6.23 Benchmark (100 commands)

ig v1.4.0 vs ripgrep

Daemon mode (1,001 queries)

Scaling — ig gets faster on larger projects

On the Linux kernel (92K files), a zero-result search: 28ms with ig vs 5,279ms with rg — 189x speedup.

Optimal codebase exploration strategy

Tested on a 1,609-file Laravel project — searching "how authentication works":

The optimal strategy: ig symbols | grep KEYWORD for definitions, ig -l "KEYWORD" for file discovery, then ig read -s (signatures only) for the key files. 700x faster than sequential exploration.

Test suite results

65 integration tests across 9 categories:

How it works

The pipeline

regex pattern
    │
    ▼
regex-syntax::Extractor → extract literal sequences
    │
    ▼
build_covering_ngrams() → minimal set of sparse n-grams
    │
    ▼
FNV-1a hash → NgramKey (u64) → lookup in mmap'd hash table
    │
    ▼
intersect posting lists → candidate file IDs
    │
    ▼
parallel regex verification (rayon) → only on candidates
    │
    ▼
results (colored / JSON)

Sparse n-grams

Traditional trigram indexes use fixed 3-character windows. ig uses variable-length sparse n-grams based on danlark1/sparse_ngrams (the algorithm behind GitHub Code Search):

Trigrams:     23 keys → 47 candidate files
Sparse grams:  3 keys →  4 candidate files (12x better)

On-disk format (v7)

Memory-mapped. Streaming SPIMI pipeline (128MB budget). Overlay index for incremental updates.

Architecture

ig
├── index/          — Sparse n-gram index (build + query + overlay)
├── search/         — Indexed + brute-force search
├── query/          — Regex → NgramQuery conversion
├── git.rs          — Token-compressed git proxy
├── rewrite.rs      — Command rewriting engine (exit codes 0/1/2/3)
├── gain.rs         — Token savings dashboard
├── tracking.rs     — JSONL history
├── discover.rs     — Session scanner for missed savings
├── setup.rs        — Universal AI agent configuration
├── scoring.rs      — Layered Semantic Compression (entropy × weight × relevance)
├── delta.rs        — Git-aware delta reads (changed lines + enclosing context)
├── read.rs         — Smart file reading (full + signatures)
├── smart.rs        — 2-line file summaries
├── symbols.rs      — Symbol definition extraction
├── pack.rs         — Project context generator
├── ls.rs           — Compact directory listing
├── daemon.rs       — Unix socket server (sub-ms)
├── watch.rs        — File watcher + auto-rebuild
└── walk.rs         — Gitignore-aware walking

Credits

• danlark1/sparse_ngrams — sparse n-gram algorithm
• Cursor — Fast regex search — the inspiration
• GitHub — The technology behind code search
• BurntSushi — regex-syntax, ignore, memchr

License

MIT