For a typical agent question ("how does authentication work", "what is the main entry point", etc.), the graph returns ~2,000–3,500 tokens of targeted search hits + neighbor edges instead of forcing the agent to read every source file. The table below averages over the 5 sample questions defined in code_review_graph/token_benchmark.py.

| Repo | Snapshot SHA | naive_corpus_tokens | avg graph_tokens | Reduction |
|------|---|-----------------:|----------------:|----------:|
| fastapi | 0227991a | 951,071 | 2,169 | 528.4x |
| code-review-graph | 84bde354 | 208,821 | 2,495 | 93.0x |
| gin | 5c00df8a | 166,868 | 1,990 | 91.8x |
| flask | a29f88ce | 125,022 | 1,986 | 71.4x |
| express | b4ab7d65 | 135,955 | 3,465 | 40.6x |
| httpx | b55d4635 | 89,492 | 2,438 | 38.0x |

Median per-question reduction across the 6 repos: ~82x. The range is 38x – 528x, where 528x is the best case (fastapi, the largest corpus), not the headline.

The whole-corpus baseline above is an upper bound no real agent pays: a competent agent greps for identifiers and reads only the best-matching files. The agent_baseline eval benchmark measures that realistic baseline — a pure-python grep over the corpus, top-3 files by match count, token-counted and compared to the graph query cost (evaluate/results/_agent_baseline_*.csv).

The formal eval/benchmarks/token_efficiency.py benchmark measures a different scenario — full get_review_context() JSON versus just the changed-file content of a commit — and reports ratios below 1 for small commits, because the review-context response carries impact-radius edges plus source snippets that exceed a tiny single-file diff. That is not a bug; the two benchmarks answer different questions. See <code class="ra0-md-code">docs/REPRODUCING.md</code> for the full methodology.

Since v2.3.4, review and impact tools attach a compact context_savings estimate so MCP clients can see the approximate context saved per call. In v2.3.5 the CLI surfaces this as the boxed Token Savings panel shown above (see "Token Savings panel" in the Usage section) and adds --verify to cross-check against OpenAI's cl100k_base tokenizer. Calibration data in <code class="ra0-md-code">docs/REPRODUCING.md</code> shows the estimate is within ~1% of real GPT-4 tokens in aggregate across 222 sample files.

Blast-radius analysis recovers every file in the ground truth on all 13 evaluation commits — but read that as an upper bound, not as "100% recall": in this mode the ground truth (changed files + files with call/import edges into them) is derived from the same graph the predictor traverses, so it is circular by construction. The over-prediction visible in the precision column is a deliberate trade-off: better to flag too many files than miss a broken dependency.

| Repo | Commits | Avg F1 | Avg Precision | Recall (graph-derived upper bound) |
|------|--------:|-------:|--------------:|-------:|
| httpx | 2 | 0.864 | 0.786 | 1.0 |
| fastapi | 2 | 0.834 | 0.750 | 1.0 |
| code-review-graph | 2 | 0.734 | 0.584 | 1.0 |
| express | 2 | 0.667 | 0.500 | 1.0 |
| flask | 2 | 0.628 | 0.481 | 1.0 |
| gin | 3 | 0.609 | 0.439 | 1.0 |
| Average | 13 | 0.714 | 0.578 | 1.000 |

The benchmark also runs an honest co-change mode: the predictor is seeded with a single changed file and graded against the other files the author actually touched in the same commit — independent-ish evidence from git history, not from the graph. Both modes appear side by side in the result CSVs (ground_truth_mode column). Co-change numbers will be added to the canonical stats once captured by the eval runner; we do not quote them before measuring.

| Repo | Files | Nodes | Edges | Flow Detection | Search Latency |
|------|------:|------:|------:|---------------:|---------------:|
| express | 141 | 1,910 | 17,553 | 106ms | 0.7ms |
| fastapi | 1,122 | 6,285 | 27,117 | 128ms | 1.5ms |
| flask | 83 | 1,446 | 7,974 | 95ms | 0.7ms |
| gin | 99 | 1,286 | 16,762 | 111ms | 0.5ms |
| httpx | 60 | 1,253 | 7,896 | 96ms | 0.4ms |

| Command | Description |
|---------|-------------|
| /code-review-graph:build-graph | Build or rebuild the code graph |
| /code-review-graph:review-delta | Review changes since last commit |
| /code-review-graph:review-pr | Full PR review with blast-radius analysis |

code-review-graph install          # Auto-detect and configure all platforms
code-review-graph install --platform <name>  # Target a specific platform
code-review-graph uninstall --dry-run  # Preview safe removal of installed artifacts
code-review-graph build            # Parse entire codebase
code-review-graph update           # Incremental update (changed files only)
code-review-graph status           # Graph statistics
code-review-graph watch            # Auto-update on file changes
code-review-graph visualize        # Generate interactive HTML graph
code-review-graph visualize --format json      # Export local graph data as JSON
code-review-graph visualize --format graphml   # Export as GraphML
code-review-graph visualize --format svg       # Export as SVG
code-review-graph visualize --format obsidian  # Export as Obsidian vault
code-review-graph visualize --format cypher    # Export as Neo4j Cypher
code-review-graph wiki             # Generate markdown wiki from communities
code-review-graph detect-changes --brief         # Risk panel + token savings (read-only)
code-review-graph update --brief                 # Refresh graph + same panel
code-review-graph detect-changes --brief --verify  # Cross-check vs tiktoken
code-review-graph register <path>  # Register repo in multi-repo registry
code-review-graph unregister <id>  # Remove repo from registry
code-review-graph repos            # List registered repositories
code-review-graph daemon start     # Start multi-repo watch daemon
code-review-graph daemon stop      # Stop the daemon
code-review-graph daemon status    # Show daemon status and repos
code-review-graph eval             # Run evaluation benchmarks
code-review-graph serve            # Start MCP server

JSON exports stay inside the local graph data directory, which Git ignores by
default. They can contain absolute paths and code-structure metadata, so inspect
and sanitize an export before publishing it outside your machine.

Both commands print the same compact panel showing how many tokens the
graph saved you compared to handing the changed files to an agent raw.
They differ in one thing: whether the graph gets refreshed first.

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context used:           762 tokens                     │
│ Saved:                     12,159 tokens (~94%)              │
│ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83   │
└──────────────────────────────────────────────────────────────┘

| Command | What it does | When to use |
|---|---|---|
| detect-changes --brief | Read-only. Looks at your current changes, queries the existing graph, prints the panel. ~1 sec. | Most of the time — the hooks (or crg-daemon) keep the graph fresh in the background, so this is enough. |
| update --brief | Re-parses your changed files into the graph first, then prints the same panel. ~5 sec. | After a rebase, a large change set, or any time you suspect the graph is stale. |

Both end with the same panel because both call the same analyze_changes() step at the end. The difference is whether the graph itself got refreshed before that analysis ran.

Add --verify to either command to cross-check the displayed numbers against OpenAI's cl100k_base tokenizer (the GPT-4 family). Requires pip install tiktoken. The estimate stays within ~1% of real tokens on a typical change set — see <code class="ra0-md-code">docs/REPRODUCING.md</code> for the calibration data.

The same context_savings metadata is also attached automatically to the JSON responses of get_impact_radius, get_review_context, detect_changes, and get_architecture_overview MCP tools, so AI agents can surface the savings to humans in chat without any extra prompting.

If your editor doesn't support hooks (e.g. Cursor, OpenCode), or you just want your
graph to stay fresh in the background without any editor integration, the daemon is
for you. It watches your repos for file changes and automatically rebuilds the graph
— no manual build or update commands needed.

The daemon is included with code-review-graph — no separate install required.

Quick setup:

# 1. Register the repos you want to watch
crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b

# 2. Start the daemon (runs in the background)
crg-daemon start

# 3. That's it — graphs stay up to date automatically
crg-daemon status                 # check daemon and per-repo watcher status
crg-daemon logs --repo proj-a -f  # tail logs for a specific repo
crg-daemon stop                   # stop daemon and all watcher processes

Also available as code-review-graph daemon start|stop|status|....

Under the hood, crg-daemon add writes to a TOML config file at
~/.code-review-graph/watch.toml. You can also edit this file directly:

[[repos]]
path = "/home/user/project-a"
alias = "proj-a"

[[repos]]
path = "/home/user/project-b"
alias = "project-b"

The daemon monitors this config file for changes and automatically starts/stops
watcher processes as repos are added or removed. Health checks every 30 seconds
restart dead watchers. No external dependencies required.

See docs/COMMANDS.md for the
full config reference and all available options.

Your AI assistant uses these automatically once the graph is built.

| Tool | Description |
|------|-------------|
| build_or_update_graph_tool | Build or incrementally update the graph |
| run_postprocess_tool | Re-run flow detection, community detection, and FTS indexing |
| get_minimal_context_tool | Ultra-compact context (~100 tokens) — call this first |
| get_impact_radius_tool | Blast radius of changed files |
| get_review_context_tool | Token-optimised review context with structural summary |
| query_graph_tool | Callers, callees, tests, imports, inheritance queries |
| traverse_graph_tool | BFS/DFS traversal from any node with token budget |
| semantic_search_nodes_tool | Search code entities by name or meaning |
| embed_graph_tool | Compute vector embeddings for semantic search |
| list_graph_stats_tool | Graph size and health |
| get_docs_section_tool | Retrieve documentation sections |
| find_large_functions_tool | Find functions/classes exceeding a line-count threshold |
| list_flows_tool | List execution flows sorted by criticality |
| get_flow_tool | Get details of a single execution flow |
| get_affected_flows_tool | Find flows affected by changed files |
| list_communities_tool | List detected code communities |
| get_community_tool | Get details of a single community |
| get_architecture_overview_tool | Architecture overview from community structure |
| detect_changes_tool | Risk-scored change impact analysis for code review |
| get_hub_nodes_tool | Find most-connected nodes (architectural hotspots) |
| get_bridge_nodes_tool | Find chokepoints via betweenness centrality |
| get_knowledge_gaps_tool | Identify structural weaknesses and untested hotspots |
| get_surprising_connections_tool | Detect unexpected cross-community coupling |
| get_suggested_questions_tool | Auto-generated review questions from analysis |
| refactor_tool | Rename preview, dead code detection, suggestions |
| apply_refactor_tool | Apply a previously previewed refactoring |
| generate_wiki_tool | Generate markdown wiki from communities |
| get_wiki_page_tool | Retrieve a specific wiki page |
| list_repos_tool | List registered repositories |
| cross_repo_search_tool | Search across all registered repositories |

MCP Prompts (5 workflow templates):
review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check

To exclude paths from indexing, create a .code-review-graphignore file in your repository root:

generated/**
*.generated.ts
vendor/**
node_modules/**

Note: in git repos, only tracked files are indexed (git ls-files), so gitignored files are skipped automatically. Use .code-review-graphignore to exclude tracked files or when git isn't available.

Optional dependency groups:

pip install "code-review-graph[embeddings]"          # Local vector embeddings (sentence-transformers)
pip install "code-review-graph[google-embeddings]"   # Google Gemini embeddings
pip install "code-review-graph[communities]"         # Community detection (igraph)
pip install "code-review-graph[enrichment]"          # Python call-resolution enrichment (Jedi)
pip install "code-review-graph[eval]"                # Evaluation benchmarks (matplotlib)
pip install "code-review-graph[wiki]"                # Wiki generation with LLM summaries (ollama)
pip install "code-review-graph[all]"                 # All optional dependencies

Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| CRG_GIT_TIMEOUT | Timeout in seconds for Git operations | 30 |
| CRG_DATA_DIR | Override directory for graph databases and generated graph artefacts | - |
| CRG_EMBEDDING_MODEL | Default model for vector embeddings | all-MiniLM-L6-v2 |
| CRG_ACCEPT_CLOUD_EMBEDDINGS | Suppress the cloud embedding egress warning after explicit acknowledgement | - |
| CRG_ALLOW_REMOTE_CODE | Allow HuggingFace models that require trust_remote_code=True | 0 |
| CRG_MAX_IMPACT_NODES | Maximum nodes to include in impact analysis | 500 |
| CRG_MAX_IMPACT_DEPTH | Search depth for blast-radius analysis | 2 |
| CRG_MAX_BFS_DEPTH | Maximum depth for graph traversal | 15 |
| CRG_MAX_CHANGED_FUNCS | Maximum changed functions analysed in one change report | 500 |
| CRG_MAX_TRANSITIVE_FRONTIER | Maximum frontier size for transitive caller/callee expansion | 50 |
| CRG_TOOL_TIMEOUT | Optional timeout in seconds for bounded MCP tools (0 disables timeout) | 0 |
| CRG_RECURSE_SUBMODULES | Include git submodules in file collection when set to 1, true, or yes | - |
| CRG_TOOLS | Comma-separated allowlist of MCP tools to expose when serving | - |
| GOOGLE_API_KEY | API key for Google Gemini embeddings | - |
| MINIMAX_API_KEY | API key for MiniMax embeddings | - |
| CRG_OPENAI_BASE_URL | OpenAI-compatible embeddings endpoint | - |
| CRG_OPENAI_API_KEY | API key for OpenAI-compatible embeddings | - |
| CRG_OPENAI_MODEL | Model name for OpenAI-compatible embeddings | - |
| CRG_OPENAI_DIMENSION | Pin embedding dimension (v3 models support reduction) | - |
| NO_COLOR | If set, disables ANSI colors in terminal | - |
| CRG_SERIAL_PARSE | If 1, disables parallel parsing (use for debugging) | - |

OpenAI-compatible embeddings (real OpenAI, Azure, or any self-hosted gateway like
new-api / LiteLLM / vLLM / LocalAI / Ollama in openai mode) need no extra install —
just set the environment variables and pass provider="openai" to embed_graph:

export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1     # or https://api.openai.com/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small          # whatever your gateway serves
# optional:
export CRG_OPENAI_DIMENSION=1536                        # pin dim (v3 models support reduction)
export CRG_OPENAI_BATCH_SIZE=100                        # lower for gateways with tight limits
                                                        # (e.g. Qwen text-embedding-v4 caps at 10)

The cloud-egress warning is auto-skipped when the base URL points to localhost
(127.0.0.1, localhost, 0.0.0.0, ::1).

> Model selection tip. Avoid -preview / -beta / -exp model IDs
> (e.g. google/gemini-embedding-2-preview) for anything you plan to keep
> long-term — preview models can change weights (different dimension → full
> re-embed required) or be deprecated without notice. Prefer stable GA
> releases such as text-embedding-3-small / text-embedding-3-large (OpenAI),
> Qwen/Qwen3-Embedding-8B (via self-hosted vLLM / LocalAI), or
> gemini-embedding-001 (via the native Gemini provider, which requires
> GOOGLE_API_KEY instead of the OpenAI-compatible path).
>
> code-review-graph embeds identifiers, signatures, structural context, and a
> bounded first-paragraph docstring/doc-comment summary. It does not transmit
> function bodies. Graphs created before documentation extraction was added
> need one full code-review-graph build before re-embedding so every file is
> reparsed. Routine builds never refresh embeddings by default. To refresh an
> existing index after a build, explicitly pass both --embedding-provider
> and --embedding-model; cloud choices may transmit this source-derived text
> and incur API cost.

Tool Filtering

CRG exposes 30 MCP tools by default. In token-constrained environments, you can
limit the server to a subset of tools using --tools or the CRG_TOOLS
environment variable:

# Via CLI flag
code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool

# Via environment variable
CRG_TOOLS=query_graph_tool,semantic_search_nodes_tool code-review-graph serve

The CLI flag takes precedence over the environment variable. When neither is set,
all tools are available. This is especially useful for MCP client configurations:

{
  "mcpServers": {
    "code-review-graph": {
      "command": "code-review-graph",
      "args": ["serve", "--tools", "query_graph_tool,semantic_search_nodes_tool,detect_changes_tool,get_review_context_tool"]
    }
  }
}

Edit code_review_graph/parser.py and add your extension to EXTENSION_TO_LANGUAGE along with node type mappings in _CLASS_TYPES, _FUNCTION_TYPES, _IMPORT_TYPES, and _CALL_TYPES. Include a test fixture and open a PR.