🤖 AI Shinobi Techniques

Agent Integration

How to give your AI agent the speed of a jonin. Sub-millisecond codebase search, structured JSON output, 35x fewer tokens than reading files.

⚡ Why CLI beats MCP

35x

fewer tokens than reading file contents via MCP

✗ MCP file read approach

•Read entire file to find pattern
•1000+ tokens per file
•Need to guess which files to read
•Slow: network round-trips
•Context window fills quickly

✓ ig CLI approach

•Only matching lines returned
•~30 tokens per match
•Index finds relevant files instantly
•0.9ms local process
•Structured JSON, easy to parse

🤖 Claude Code Integration

Claude Code uses ig as its primary codebase search tool when available. It falls back to ripgrep otherwise. The JSON output lets Claude parse results without regex.

Claude Code uses ig like this

# Claude searching for function implementations
ig --json "fn build_covering_ngrams" src/

{
  "matches": [{"file": "src/index/ngram.rs", "line": 142, "text": "pub fn build_covering_ngrams..."}],
  "stats": {"duration_ms": 0.9, "candidates": 2, "matches": 1}
}

# Claude finding all public API surface
ig --json --type rs "^pub (fn|struct|enum|trait)" src/

# Claude finding TODO items before a refactor
ig --json -i "TODO|FIXME|HACK" .

ℹ

Configuration: ig is configured as a Bash tool in Claude Code's environment. Claude calls ig --json and receives structured results without needing to read full file contents.

🧑‍💻 Codex and Other Agent Integration

Any agent with shell access can use ig. Build the index once, then query from any agent or script.

agent setup script

#!/bin/bash
# Set up ig for agent use

# 1. Build index at session start
ig index "$PROJECT_ROOT"

# 2. Start daemon for sub-ms queries
ig daemon "$PROJECT_ROOT" &

# 3. Agent can now use ig query for all searches
RESULT=$(ig query --json "$PATTERN" "$PROJECT_ROOT")
echo "$RESULT" | jq '.matches[] | .file + ":" + (.line|tostring)'

Python agent integration

import subprocess, json

def search_codebase(pattern: str, path: str = ".") -> list:
    """Search codebase with instant-grep. Returns list of matches."""
    result = subprocess.run(
        ["ig", "--json", pattern, path],
        capture_output=True,
        text=True
    )
    data = json.loads(result.stdout)
    return data["matches"]

# Usage
matches = search_codebase("async fn", "./src")
for m in matches:
    print(f"{m['file']}: {m['text'].strip()}")

📦 JSON Output Format

The --json flag outputs a single JSON object. Always valid JSON — even with zero matches. Easy to pipe to jq.

full JSON schema

{
  "pattern": "<regex string>",
  "matches": [
    {
      "file":    "<relative path from index root>",
      "line":    <1-based line number>,
      "text":    "<raw line content>",
      "before":  [...context lines]  // only with -B or -C
      "after":   [...context lines]  // only with -A or -C
    }
  ],
  "stats": {
    "duration_ms":    <float>,
    "candidates":    <int — files passing index filter>,
    "files_searched": <int — total files in index>,
    "matches":       <int — total match count>
  }
}

Token count comparison

Read 10 full files (MCP): ~12,000 tokens

ig search --json (10 matches): ~350 tokens

Savings: 35x fewer tokens

jq recipes for agents

file:line list
ig --json "pat" . | jq '.matches[] | "\(.file):\(.line)"'
just file paths
ig --json "pat" . | jq '[.matches[].file] | unique'

🔄 Daemon Mode for High-Frequency Agents

Agents often search the same codebase dozens of times per session. The Sage Mode daemon eliminates repeated index loading overhead.

recommended agent session setup

# 1. At session start: build + start daemon
ig index . && ig daemon . &

# 2. All agent searches use daemon (0.3ms)
ig query --json "$PATTERN" .

# 3. If code changes during session: re-index
ig index .  # daemon auto-detects and hot-reloads

# 4. At session end: daemon exits automatically

~15ms

First query (cold)

with index build

0.9ms

Warm queries

ig search

0.3ms

Daemon queries

ig query