๐ 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 | iexcolgrep --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/projectcolgrep 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-105agent/src/llm/server.rs:65-69agent/src/llm/llama.rs:101-101agent/src/llm/llama.rs:115-116agent/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 Codecolgrep --install-codex # Codexcolgrep --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 followed by reinforcement learning (RL) using GRPO.
We construct multilingual code-localization environments from nebius/SWE-rebench, internlm/SWE-Fixer-Train-110K, and additional scraped repositories covering multiple programming languages. Each training instance pairs a repository with an issue description and a dedicated bug-fix commit. We use the pre-patch repository state as the search environment and derive gold file- and line-level localization targets from the corresponding patch. These data sources are used across both the SFT and RL stages.
We first perform a short cold-start SFT phase using traces generated and filtered with Qwen3.5-27B as a teacher model. This stage teaches tool-call formatting, command ordering, argument and flag usage, and effective repository exploration strategies, with an emphasis on semantic search through ColGrep rather than traditional grep-based search. We then train for 500 steps using GRPO in a dedicated code-localization environment, rewarding accurate file- and line-level identification while penalizing unnecessary exploration steps.
The model operates in a repository exploration environment with access to three tools:
Table with columns: Tool, Purpose| Tool | Purpose |
|---|
colgrep | Search code semantically, with optional regex and path filters. |
terminal | Read files and inspect the repository through read-only commands. |
finish | Submit relevant locations as path/to/file:START-END. |
The agent has a 10-turn budget to search and inspect the repository before submitting its final prediction as a set of relevant file paths and line ranges.
๐ Evaluation

We evaluate ColGREP-Agent-2B on SWE-bench Lite and Multi-SWE-bench Flash, adapting both benchmarks into code-localization tasks following the methodology described in our paper. Rather than generating patches or resolving issues end-to-end, the model is tasked with identifying the files and lines of code relevant to each issue. This allows us to evaluate localization accuracy independently of code generation.
All models use the ColGREP harness. File and line F1 measure overlap with reference files and lines, respectively. Scores are percentages averaged over five seeds (300 instances per benchmark per seed), using strict predictions without rescue, a 10-turn limit with mandatory final submission, and temperature 0.6 without reasoning for comparison models.
๐ Citation
@misc{colgrepagent_2026, title = {ColGrep-Agent}, author = {Lasbordes, Maxence and Sourty, Raphael and Sinha, Aarush and Chatelain, Amรฉlie}, year = {2026}, howpublished = {\url{https://huggingface.co/blog/lightonai/colgrep-agent/}}}