Skip to content

cgrep Docs

Local-first code search for developers and AI coding agents.

Current release: v1.5.2

Canonical Decision Tree

Choose the path that matches your task:

Human CLI fast path

cgrep s "token validation" src/
cgrep read src/auth.rs
cgrep d handle_auth
cgrep r handle_auth
cgrep c handle_auth

Agent / MCP fast path

cgrep map --depth 2
ID=$(cgrep agent locate "where token validation happens" --compact | jq -r '.results[0].id')
cgrep agent expand --id "$ID" -C 8 --compact
cgrep read src/auth.rs
cgrep d handle_auth
cgrep r handle_auth

Optional stage 0

If the task is broad or ambiguous, start with:

cgrep --format json2 --compact agent plan "trace authentication middleware flow"

Start Here (2 Minutes)

# Install
curl -fsSL https://raw.githubusercontent.com/meghendra6/cgrep/main/scripts/install_release.sh | bash

# Human CLI quickstart
cgrep s "token validation" src/
cgrep read src/auth.rs
cgrep d handle_auth

By Goal

Goal Open this page
Install quickly Installation
Learn daily commands Usage
Set up AI-agent retrieval Agent Workflow
Connect MCP hosts MCP
Keep index warm while coding Indexing and Daemon
Fix common issues Troubleshooting

AI Agent Setup (Required vs Optional)

# One-time install (choose one)
cgrep agent install codex
cgrep agent install claude-code
cgrep agent install cursor
cgrep agent install copilot
cgrep agent install opencode
  • Required: restart the agent session once.
  • Not required for normal usage: manual cgrep index or cgrep daemon start.
  • Optional CLI retrieval examples are in agent.md.
  • Canonical workflow details are mirrored in usage.md, agent.md, and mcp.md.

Benchmark Snapshot (PyTorch, Codex, runs=2)

  • Date: February 22, 2026 (UTC)
  • Baseline billable tokens: 151,466
  • cgrep billable tokens: 69,874
  • Billable token reduction: 53.9%

Reports: - Codex Agent Efficiency - Search Option Performance - Agent Token Efficiency

Language