Skip to content

Agent Workflow

Use cgrep to keep AI coding-agent retrieval loops short and deterministic.

Canonical 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

Use cgrep agent plan "..." as an optional CLI-only stage 0 when the task is broad, ambiguous, or multi-step. If map -> locate -> expand is already clear, skip plan.

If locate is noisy, empty, slow, or the MCP client reports an output cap, rescope first:

  1. path
  2. glob
  3. changed
  4. file_type

Then lower limit / context, and prefer profile=agent (or CLI --budget tight) before widening again.

1) Install for Your Host

cgrep agent install codex
cgrep agent install claude-code
cgrep agent install cursor
cgrep agent install copilot
cgrep agent install opencode

2) What is Required vs Optional

  • Required: restart the current agent session once after installation.
  • Not required for normal use: manual cgrep index or always-on daemon.
  • Optional: run cgrep daemon start during long, high-churn coding sessions.

3) Optional Low-Token Two-Stage Retrieval (CLI)

# Stage 1: map or locate candidates
cgrep map --depth 2
ID=$(cgrep agent locate "where token validation happens" --compact | jq -r '.results[0].id')

# Stage 2: expand only selected candidate
cgrep agent expand --id "$ID" -C 8 --compact

4) Optional Deterministic Retrieval Plan (CLI-only stage 0)

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

Useful options: - --max-steps <n> - --max-candidates <n> - --budget tight|balanced|full|off - --path, --changed

Positioning: - agent plan is a CLI preflight helper, not an MCP tool. - Use it before the normal fast path only when you need deterministic orchestration. - Preferred default loop remains: map -> locate -> expand -> read -> definition/references/callers.

5) Search mode vs retrieval profile

When you wire cgrep into an agent or MCP client, keep these separate:

  • mode = search engine choice
  • keyword
  • semantic
  • hybrid
  • profile = retrieval defaults / output ergonomics
  • human
  • agent
  • fast

Example:

# Explicit engine
cgrep --format json2 --compact s "retry budget" --mode keyword

# Agent-friendly retrieval defaults
cgrep --format json2 --compact s "retry budget" --profile agent -B tight

For MCP compatibility, mode=auto and mode=default mean “use the current default search behavior.” They are compatibility aliases, not separate engine modes.

  • Prefer cgrep-first flow: map -> locate -> expand -> read -> definition/references/callers
  • Treat agent plan as optional fallback / stage 0, not the default starting point
  • Scope early with -p, --glob, --changed
  • Use --format json2 --compact for deterministic parsing

Uninstall

cgrep agent uninstall codex
cgrep agent uninstall claude-code
cgrep agent uninstall cursor
cgrep agent uninstall copilot
cgrep agent uninstall opencode

Validate Quickly

codex mcp list
cgrep --format json2 --compact s "DispatchKeySet" -p c10/core

MCP sanity examples:

{"query":"auth flow","mode":"auto"}
{"query":"auth flow","profile":"agent"}