Architecture
Code Architecture Guide
How Pretense uses code-review-graph to build a knowledge graph of the codebase
What is code-review-graph
code-review-graph is a Tree-sitter-powered SQLite graph that parses every function, class, and import across the entire Pretense monorepo into a queryable knowledge graph. It exposes 22 MCP tools that give Claude sub-symbol precision, delivering 4.9x to 27.3x token reduction compared to reading raw source files.
Quick Start
Get the graph running in your project. The post-commit hook keeps it automatically up to date after every commit.
# Install pip install code-review-graph # Build graph (one-time) code-review-graph build # Check status code-review-graph status # Auto-update on commits (already wired via .husky/post-commit)
The Husky post-commit hook in .husky/post-commit runs code-review-graph update automatically. No manual re-builds needed after the first run.
MCP Tools Reference
Key tools from the 22-tool MCP server. Register the server in .claude/settings.json to use them inside Claude Code.
| Tool | Purpose |
|---|---|
build_or_update_graph_tool | Build or incrementally update the graph |
semantic_search_nodes_tool | Semantic search for functions/classes |
get_impact_radius_tool | Blast radius from a changed file/function |
get_architecture_overview_tool | Community-based module map |
detect_changes_tool | Risk-scored impact analysis |
list_flows_tool | Execution flows sorted by criticality |
generate_wiki_tool | Generate markdown architecture docs |
cross_repo_search_tool | Search across all 32 packages |
Graph-first navigation
Follow these three rules when navigating the Pretense codebase with Claude. They minimise token usage and maximise accuracy.
Use semantic_search_nodes_tool before Grep
Graph-aware semantic search finds exact symbols faster and with less token cost than file-based grep.
Use get_minimal_context_tool before Read
Fetches only the lines relevant to your task. Reading whole files is wasteful when the graph knows exactly what you need.
Use get_impact_radius_tool before editing any function
Know what breaks before you touch it. The graph calculates transitive callers and dependents in milliseconds.
Code graph dashboard
View your live code graph at the dashboard preview. Explore module clusters, search nodes, and inspect impact radii without leaving the browser.
View code graph dashboardGitHub Actions integration
Every PR gets an automatic blast-radius analysis comment via .github/workflows/code-review.yml. The workflow runs detect_changes_tool against the diff, calculates risk scores, and posts a structured comment listing affected modules and suggested reviewers.
- name: Blast-radius analysis
run: |
code-review-graph detect-changes \
--base ${{ github.event.pull_request.base.sha }} \
--head ${{ github.event.pull_request.head.sha }} \
--format github-comment | gh pr comment $PR --body-file -The comment includes a risk score (0-100), a list of directly changed symbols, and the transitive blast radius across all 32 packages.
Next steps
Explore more of the Pretense documentation.