pi-mono-colgrep

Pi coding agent extension for ColGREP — semantic code search powered by ColBERT late-interaction embeddings.

Benchmark Results: See BENCHMARK.md for full paper-grade benchmark comparing ColGREP (CPU + GPU) vs grep on 20 corpora × 60 queries.

---

Benchmark Highlights

We ran a paper-grade benchmark on 20 local corpora (3 medium Rust repos + 17 Terminal Bench tasks) with 60 natural-language queries.

Accuracy: Semantic vs Keyword

Latency: GPU vs CPU vs grep

Key insight: GPU brute-force MaxSim (no index) outperforms CPU PLAID in both accuracy (+12-13% MRR) and latency (-94% p50). Edge 17M model is optimal for small-to-medium corpora.

Full methodology, per-repository breakdown, and LaTeX-ready figure data: BENCHMARK.md

---

Quick Start for AI Agents

If you are an AI coding agent (Claude, GPT, Codex, pi, etc.) installing this extension, use these commands:

# 1. Install ColGREP CLI (required dependency)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lightonai/next-plaid/releases/latest/download/colgrep-installer.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# 2. Install as pi package (recommended)
pi install git:github.com/sionic-ai/pi-colgrep-plugins

# 3. Verify installation
colgrep --version
pi list | grep colgrep

What this gives you:

• semantic_search tool — search code by meaning, not just keywords
• colgrep CLI — direct terminal access to semantic search
• Skills — usage guidance automatically loaded into your context

First-time indexing (do this once per repo):

colgrep init -y .

---

Features

• Semantic Code Search — Find code by meaning, not just keywords
• ColBERT Embeddings — Multi-vector late-interaction for precise matching
• GPU Acceleration — PyTorch CUDA brute-force MaxSim for 16ms p50 latency
• Hybrid Search — Combine regex patterns with semantic ranking
• Fast After First Query — Index once, search instantly (CPU); or no index needed (GPU)
• Native Pi Integration — semantic_search tool and session hooks

---

Installation Options

Option 1: Pi Package (Recommended)

The standard way to install pi extensions:

# Prerequisites: ColGREP CLI
brew install lightonai/tap/colgrep
# or
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lightonai/next-plaid/releases/latest/download/colgrep-installer.sh | sh

# Install the pi package
pi install git:github.com/sionic-ai/pi-colgrep-plugins

# Verify
pi list

Option 2: Makefile (Offline / Air-gapped)

For environments without network access or when you need full control:

git clone https://github.com/sionic-ai/pi-colgrep-plugins
cd pi-colgrep-plugins

# Show all available commands
make help

# Vendor dependencies for offline builds
make init

# Build and install everything
make install

# Verify
make smoke-test

Makefile targets:

Option 3: Manual

npm install
npm run build
mkdir -p ~/.pi/agent/extensions ~/.pi/agent/skills
cp dist/extensions/colgrep.js ~/.pi/agent/extensions/
cp -r skills/* ~/.pi/agent/skills/

---

Usage

In Pi (as a tool)

The extension registers a semantic_search tool that the model can use:

User: Find code that handles database connection pooling

Assistant: I'll search for database connection pooling code.
[Uses semantic_search with query: "database connection pooling"]

Found 5 matches:
src/db/pool.rs:45: pub fn create_pool(config: &DbConfig) -> Pool<...>
...

Direct CLI Usage

# Semantic search
colgrep "authentication middleware"

# Regex + semantic hybrid
colgrep -e "async fn" "error handling"

# Filter by file type
colgrep --include="*.ts" "React component"

# Search specific directory
colgrep "logging setup" ./src/utils

# GPU acceleration (if available)
colgrep --force-gpu "containerized execution"

---

For AI Agents: Tool Reference

semantic_search

Parameters:

• query (string, required): Natural language description of what you're looking for
• pattern (string, optional): Regex pre-filter (e.g., "async fn")
• include (string, optional): Glob filter (e.g., "*.py")
• path (string, optional): Directory to search (default: current directory)
• k (number, optional): Max results (default: 10)

When to use:

• Finding code by behavior ("error handling in authentication")
• Searching for concepts ("database connection pooling")
• Locating functions by purpose, not name
• Combining regex with semantic ranking

When NOT to use:

• Exact string matching (use grep/rg)
• File name search (use find/fd)
• Simple pattern matching (use grep)

Example tool calls:

{"query": "authentication middleware", "path": "./src"}
{"query": "error handling", "pattern": "async fn", "include": "*.rs"}
{"query": "React form validation", "k": 20}

---

How It Works

┌─────────────────────────────────────────────────────────────────────────┐
│                    ColGREP Pipeline                           │
├─────────────────────────────────────────────────────────────────────────┤
│  1. Tree-sitter    → Parse code into functions/classes       │
│  2. Analysis       → Extract signatures, calls, imports     │
│  3. LateOn-Code    → Generate multi-vector embeddings       │
│  4. PLAID Index    → Quantized, memory-mapped storage (CPU) │
│  5. MaxSim Search  → Token-level matching + RRF fusion      │
│  6. GPU BruteForce → CUDA-accelerated exact MaxSim (GPU)    │
└─────────────────────────────────────────────────────────────────────────┘

Why Late Interaction?

pi-colgrep is designed for code search, where every repository is effectively its own domain. Late interaction models keep richer token-level representations and defer part of the matching step until retrieval time, preserving fine-grained evidence during ranking.

For code search, this matters because:

• Each codebase has unique naming conventions and abstractions
• Identifiers often carry important semantic meaning
• Exact or near-exact token matches can be decisive
• Queries are often short or phrased differently from the code

GPU Acceleration

When a CUDA-capable GPU is available, ColGREP can use PyTorch brute-force MaxSim instead of PLAID indexing:

Trade-off: GPU uses more memory but is dramatically faster and more accurate for small-to-medium corpora. For >100K files, PLAID indexing is still required.

---

Configuration

The extension reads ColGREP's native config at ~/.config/colgrep/config.json.

colgrep settings --k 20           # Default result count
colgrep settings --n 10           # Context lines
colgrep settings --int8           # Faster inference
colgrep settings --relative-paths # Shorter output

GPU-specific settings:

# Force GPU mode (if auto-detection fails)
colgrep --force-gpu "query"

# Use Edge model (faster, smaller)
colgrep --model lightonai/LateOn-Code-edge "query"

---

Troubleshooting

colgrep: command not found

export PATH="$HOME/.local/bin:$PATH"
command -v colgrep
colgrep --version

First search is slow

The first query builds the index. Pre-build it:

colgrep init -y /path/to/project

Or use GPU mode (no index build needed):

colgrep --force-gpu "query" /path/to/project

GPU not detected

# Check CUDA
nvidia-smi
python3 -c "import torch; print(torch.cuda.is_available())"

# ColGREP auto-detects GPU; if it fails, use --force-gpu
colgrep --force-gpu "test query"

Pi does not show the semantic_search tool

# Reinstall and restart
pi remove git:github.com/sionic-ai/pi-colgrep-plugins
pi install git:github.com/sionic-ai/pi-colgrep-plugins
# Then restart pi

Search returns no results

colgrep status
colgrep clear && colgrep init -y .

See INSTALL.md for detailed platform-specific instructions.

---

Package Structure

pi-colgrep-plugins/
├── extensions/
│   └── colgrep.ts           # Main extension (semantic_search tool)
├── skills/
│   ├── colgrep-usage/       # General usage guidance
│   └── colgrep-semantic-search/  # Tool-specific guidance
├── package.json             # Pi package manifest (pi.extensions, pi.skills)
├── BENCHMARK.md             # Full benchmark report (20 corpora × 60 queries)
├── README.md                # This file
└── Makefile                 # Offline build automation

---

Related Projects

• ColGREP — The semantic code search CLI
• NextPlaid — Multi-vector search engine (Rust)
• PyLate — ColBERT training library
• Pi Coding Agent — The coding agent runtime

---

License

MIT