colgrep 1.0.0

Semantic code search powered by ColBERT
Documentation

Semantic code search powered by ColBERT multi-vector embeddings and the PLAID algorithm.

Installation

Pre-built Binaries (Recommended)

macOS / Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lightonai/nxt-plaid/releases/latest/download/colgrep-installer.sh | sh

Windows (PowerShell):

powershell -c "irm https://github.com/lightonai/nxt-plaid/releases/latest/download/colgrep-installer.ps1 | iex"

Specific Version:

# Replace 0.4.0 with desired version
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lightonai/nxt-plaid/releases/download/0.4.0/colgrep-installer.sh | sh

Using Cargo (crates.io)

If you don't have Cargo installed, install Rust first:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then install colgrep:

cargo install colgrep

Build from Source

git clone https://github.com/lightonai/nxt-plaid.git
cd nxt-plaid
cargo install --path colgrep

Build Features

Feature Platform Description
accelerate macOS Apple Accelerate for vector operations
coreml macOS Apple CoreML for model inference
openblas Linux OpenBLAS for vector operations
cuda Linux/Windows NVIDIA CUDA for model inference
tensorrt Linux NVIDIA TensorRT for model inference
directml Windows DirectML for model inference

Examples:

# macOS with Apple Accelerate + CoreML (recommended for M1/M2/M3/M4)
cargo install --path colgrep --features "accelerate,coreml"

# Linux with OpenBLAS
cargo install --path colgrep --features openblas

# Linux with CUDA GPU support
cargo install --path colgrep --features cuda

# Combine features
cargo install --path colgrep --features "openblas,cuda"

OpenBLAS Acceleration (Linux)

OpenBLAS provides optimized BLAS (Basic Linear Algebra Subprograms) for vector operations, significantly improving search performance on Linux.

Install OpenBLAS:

# Debian/Ubuntu
sudo apt install libopenblas-dev

# Fedora/RHEL/CentOS
sudo dnf install openblas-devel

# Arch Linux
sudo pacman -S openblas

Then build with the openblas feature:

cargo install --path colgrep --features openblas

Apple Accelerate + CoreML (macOS)

Apple Accelerate (vector operations) and CoreML (model inference) are built into macOS and require no additional installation. Just build with both features:

cargo install --path colgrep --features "accelerate,coreml"

This is recommended for M1/M2/M3/M4 Macs for optimal performance.

ONNX Runtime (Automatic)

ONNX Runtime is automatically downloaded on first use. No manual installation required.

The CLI searches for ONNX Runtime in:

  1. ORT_DYLIB_PATH environment variable
  2. Python environments (pip/conda/venv)
  3. System paths

If not found, it downloads to ~/.cache/onnxruntime/.

Quick Start

# Search with natural language (auto-indexes on first run)
colgrep "error handling in API"

# Search in specific directory
colgrep "database connection" /path/to/project

# Limit results
colgrep "authentication" -k 5

Search Patterns

Basic Search

colgrep "natural language query"
colgrep "function that parses JSON" ./src
colgrep "error handling" -k 10

File Type Filtering (--include)

Filter by file extension or path pattern:

# Single extension
colgrep --include="*.py" "database query"
colgrep --include="*.rs" "error handling"

# Multiple extensions
colgrep --include="*.ts" --include="*.tsx" "React component"

# Path patterns
colgrep --include="src/**/*.rs" "config parsing"
colgrep --include="**/tests/**" "test helper"
colgrep --include="*_test.go" "mock"

Pattern Syntax:

Pattern Matches
*.py All Python files
*.{ts,tsx} TypeScript and TSX files
src/**/*.rs Rust files under src/
**/tests/** Files in any tests/ directory
*_test.go Go test files
*.spec.ts TypeScript spec files

Hybrid Search (-e pattern + semantic)

First filter with grep, then rank semantically:

# Find files with "TODO", rank by semantic relevance to "error handling"
colgrep -e "TODO" "error handling"

# Find async functions, rank by "promise handling"
colgrep -e "async fn" "promise handling" --include="*.rs"

# Extended regex (-E)
colgrep -e "fn|struct" -E "rust definitions"
colgrep -e "error[0-9]+" -E "error codes"
colgrep -e "(get|set)Value" -E "accessor methods"

# Fixed string (-F) - no regex interpretation
colgrep -e "user.name" -F "user properties"

# Whole word (-w)
colgrep -e "error" -w "error handling"

Output Modes

# List files only (like grep -l)
colgrep -l "database queries"

# Show full function content
colgrep -c "authentication handler"
colgrep --content "parse config" -k 5

# JSON output
colgrep --json "authentication" | jq '.[] | .unit.file'

# Control context lines (default: 6)
colgrep -n 10 "database"

Exclusions

# Exclude file patterns
colgrep --exclude="*.test.ts" "component"
colgrep --exclude="*_mock.go" "service"

# Exclude directories (literal names)
colgrep --exclude-dir="vendor" "import"
colgrep --exclude-dir="node_modules" --exclude-dir="dist" "config"

# Exclude directories (glob patterns)
colgrep --exclude-dir="*/plugins" "query"
colgrep --exclude-dir="**/test_*" "implementation"
colgrep --exclude-dir=".claude/*" "code"

Code-Only Mode

Skip documentation and config files:

colgrep --code-only "authentication logic"

Excludes: Markdown, text, YAML, TOML, JSON, Dockerfile, Makefile, shell scripts.

Index Management

# Check index status
colgrep status

# Clear current project index
colgrep clear

# Clear all indexes
colgrep clear --all

# Show statistics
colgrep --stats

Index Locations

Platform Location
Linux ~/.local/share/colgrep/indices/
macOS ~/Library/Application Support/colgrep/indices/
Windows %APPDATA%\colgrep\indices\

Configuration

# Show current config
colgrep settings

# Set default results count
colgrep settings --k 20

# Use INT8 quantized model (default, faster)
colgrep settings --int8

# Use FP32 full precision (more accurate)
colgrep settings --fp32

# Reset to defaults (INT8, pool-factor 2)
colgrep settings --k 0 --n 0

Change Model

# Temporary (single query)
colgrep "query" --model lightonai/another-model

# Permanent
colgrep set-model lightonai/another-model

Config stored in ~/.config/colgrep/config.json.

IDE Integrations

Claude Code

colgrep --install-claude-code

IMPORTANT: You must restart Claude Code after installation for the plugin to take effect.

The integration includes intelligent hooks that:

  • Check if your project needs indexing before injecting colgrep context
  • Return empty if >3000 chunks need indexing (prevents slow operations on large projects)
  • Return empty if index is desynced (needs repair)
  • Only suggest colgrep when it's ready to use

This ensures Claude Code only uses colgrep when it will provide fast, reliable results.

To uninstall:

colgrep --uninstall-claude-code

OpenCode

colgrep --install-opencode
colgrep --uninstall-opencode

Codex

colgrep --install-codex
colgrep --uninstall-codex

Complete Uninstall

Remove colgrep from all AI tools, clear all indexes, and delete all data:

colgrep --uninstall

Supported Languages

Code (18 languages): Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Ruby, Kotlin, Swift, Scala, PHP, Lua, Elixir, Haskell, OCaml

Config: YAML, TOML, JSON, Dockerfile, Makefile

Text: Markdown, Plain text, AsciiDoc, Org

Shell: Bash, Zsh, PowerShell

How It Works

  1. Parse: Tree-sitter extracts functions, methods, classes
  2. Analyze: 5-layer analysis (AST, call graph, control flow, data flow, dependencies)
  3. Embed: ColBERT encodes each unit as multiple vectors
  4. Index: PLAID algorithm compresses and indexes vectors
  5. Search: Query encoded and matched using late interaction scoring

Embedding Input Format

Each code unit is converted to a structured text representation before being encoded by the model. Here's an example of what the model receives for a Python function:

Original code:

# src/utils/http_client.py
def fetch_with_retry(url: str, max_retries: int = 3) -> Response:
    """Fetches data from a URL with retry logic."""
    for i in range(max_retries):
        try:
            return client.get(url)
        except RequestError as e:
            if i == max_retries - 1:
                raise e

Model input:

Function: fetch_with_retry
Signature: def fetch_with_retry(url: str, max_retries: int = 3) -> Response
Description: Fetches data from a URL with retry logic.
Parameters: url, max_retries
Returns: Response
Calls: range, client.get
Variables: i, e
Uses: client, RequestError
Code:
def fetch_with_retry(url: str, max_retries: int = 3) -> Response:
    """Fetches data from a URL with retry logic."""
    for i in range(max_retries):
        try:
            return client.get(url)
        except RequestError as e:
            if i == max_retries - 1:
                raise e
File: src / utils / http client http_client.py

The file path is normalized to improve semantic matching: separators become spaced, underscores/hyphens become spaces, and CamelCase is split (e.g., HttpClient → http client).

Environment Variables

Variable Description
ORT_DYLIB_PATH Path to ONNX Runtime library
XDG_DATA_HOME Override data directory
XDG_CONFIG_HOME Override config directory

License

Apache-2.0

See Also