colgrep-agent

📄 Paper | 📝 Blog Post | 💻 GitHub | 🤗 Model | 📦 GGUF

ColGrep-Agent-2B is a lightweight code-localization agent designed to identify the files and line ranges relevant to a GitHub issue, bug report, feature request, or natural-language question about a repository.

Given a question such as "Where are retries configured?" or "Why does the export crash on empty files?", the agent iteratively searches the repository using ColGrep, reads candidate files through a read-only terminal, and returns the precise code locations relevant to the task.

The model powers colgrep --agent and is designed to offload repository exploration from larger coding agents. Rather than consuming thousands of tokens searching through files before making a fix, a larger model can delegate code localization to ColGrep-Agent-2B and receive a focused list of relevant locations.

Its small footprint enables practical local inference, with GPU acceleration when available, without requiring Python, a separate inference server, or an API key.

🚀 Quick start

1. Install ColGrep and the model

Homebrew (macOS / Linux)

brew install lightonai/tap/colgrep && colgrep --install-agent

Shell installer (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lightonai/next-plaid/releases/latest/download/colgrep-installer.sh | sh && "${CARGO_HOME:-$HOME/.cargo}/bin/colgrep" --install-agent

Windows (PowerShell)

irm https://github.com/lightonai/next-plaid/releases/latest/download/colgrep-installer.ps1 | iex
colgrep --install-agent

Cargo (from source)

cargo install colgrep && colgrep --install-agent

The colgrep --install-agent command downloads the default colgrep-agent-2B-Q8_0.gguf model (approximately 2.5 GB), verifies that it loads, and prepares the prompt cache to accelerate the first inference.

Installation is required only once. No Python environment, external inference server, or API key is necessary.

2. Index a repository

cd /path/to/project
colgrep init

After the initial indexing, subsequent searches automatically detect modified files and update the index before answering.

3. Ask a question

colgrep --agent "where does the agent decide which GPU backend llama.cpp uses"

The following example shows a real session on ColGrep's own source code, running on an M3 Pro with Metal acceleration. Individual tool results have been omitted for readability.

$ colgrep --agent "where does the agent decide which GPU backend llama.cpp uses"
◆ colgrep agent  · colgrep-agent-2B-Q8_0.gguf (GPU)
❯ where does the agent decide which GPU backend llama.cpp uses

  ● colgrep   llama.cpp GPU backend
  ● terminal  cat -n agent/src/llm/llama.rs
  ● terminal  cat -n agent/src/llm/server.rs
  ● terminal  cat -n agent/src/engine.rs
  ● terminal  cat -n agent/src/llm/llama.rs | sed -n '80,150p'
  ● terminal  cat -n agent/src/llm/server.rs | sed -n '65,130p'
  ● colgrep   find_gpu
  ● terminal  cat -n agent/src/llm/server.rs | sed -n '1,100p'
  ● finish    agent/src/llm/server.rs:103-105, agent/src/llm/server.rs:65-69, …

✓ 5 locations · 9 turns · 2 searches · 6 terminal commands · 21.7s

agent/src/llm/server.rs:103-105
agent/src/llm/server.rs:65-69
agent/src/llm/llama.rs:101-101
agent/src/llm/llama.rs:115-116
agent/src/engine.rs:57-67

The output follows the path/to/file:START-END format, making it directly usable by developers, scripts, and other coding agents.

Agent progress is printed to stderr only when running in a terminal, while stdout contains only the resulting code locations. This separation makes the command easy to compose with other tools.

Additional usage examples

Scope the search to a directory and display the matching code lines:

colgrep --agent "crash when the config file is empty" ./backend -c

Return structured JSON for downstream applications:

colgrep --agent --json "where are retries configured"

🤖 Integration with coding agents

ColGrep can be integrated into existing coding-agent workflows, allowing larger models to delegate repository exploration to a smaller specialized model.

Install the corresponding hooks and skills:

colgrep --install-claude-code   # Claude Code
colgrep --install-codex         # Codex
colgrep --install-opencode      # OpenCode

For example, once configured, Claude Code can delegate open-ended questions such as "Where is this behavior implemented?" to colgrep --agent, receiving exact file paths and line ranges instead of performing every exploratory search itself.

This division of labor allows larger coding agents to reserve more of their context and computation for understanding issues, planning changes, and generating patches.

🔎 ColGrep

ColGrep is a semantic code search tool for terminals and coding agents, built on the NextPlaid search engine. It combines natural-language search with regex filtering to find code by both meaning and exact matches.

ColGrep-Agent-2B extends this search functionality with an iterative search-and-read loop. Rather than relying on a single search query, the agent follows leads, inspects candidate files, refines its searches, and identifies relevant code locations over multiple turns.

🧠 Training and harness

ColGREP-Agent-2B is built on MiniCPM5-2B and trained in two stages: a short supervised fine-tuning (SFT) cold start foll