codewalk

Local MCP server that builds a dependency graph of a git repo and uses it for two things:

1. Structural Q&A — blast radius, cycles, reading order, architecture health, symbol lookup

2. Pre-PR code review — batched diffs with graph risk context and language/framework rubrics

Your AI agent (Cursor, Claude, Copilot, …) talks to codewalk over MCP. codewalk never calls an LLM and never edits files; the host agent does the reasoning and applies fixes.

How it works

repo on disk
    → tree-sitter parse (13 languages)
    → DuckDB graph (files, imports, symbols, calls)
    → igraph (blast radius, PageRank, betweenness, cycles, shortest paths)
    → MCP tools over stdio

• Graph lives at .codewalk/graph.duckdb in the target repo.

• Review sessions live under .codewalk/review_sessions/.

• No vector store, no API keys, no network service — stdio MCP only.

AST languages: Python, JavaScript, TypeScript, Java, Go, Rust, Ruby, C, C++, C#, PHP, Kotlin, Swift.

Related MCP server: better-code-review-graph

🎬 Demo

MCP — Overview

https://github.com/user-attachments/assets/d65d23c6-38bc-4610-b5d0-62669d85e5fd

MCP — Explain Function

https://github.com/user-attachments/assets/252a4738-3a22-4759-94f3-0ac41f7f0c09

MCP — Blast Radius

https://github.com/user-attachments/assets/052fa64b-e421-48ed-b65c-29609e0caf32

MCP — Run Review

https://github.com/user-attachments/assets/de36cdff-610b-4f4b-a422-7cff737fef2f

🔬 Code Review — Powered by the Intelligence Layer

Codewalk's review engine is built on top of the codebase intelligence layer. It doesn't just lint — it understands your architecture, knows what files are risky, and reviews with full context.

How it works

git diff → Static Analysis (graph risk, PageRank, cycles, blast radius)
         → Batch files (token-bounded, grouped by feature)
         → Host LLM reviews each batch with full context
         → Submit findings to disk per batch (JSON + Markdown, context stays clean)
         → Final summary: raw findings grouped by severity

You talk to your IDE agent; the agent calls Codewalk MCP tools. Codewalk does not render UI — each host has its own approve/reject experience (Cursor approval cards, Copilot chat, Claude Code prompts, etc.). The agent must present each fix and wait for your approval through that host UI (or yes/no in chat).

What makes it different

Zero-setup review

Review runs on any git repo — no prior codewalk_analyze_codebase needed. The dependency graph is built automatically on first review (~5s) and cached:

Severity levels

Review target (required)

Review needs an explicit target — codewalk will not assume main/master. If the agent calls review with no target, the tool returns a prompt to ask you which branch to use.

MCP review flow

1. codewalk_run_review(target_branch=...) → session + first batch (diff + risk + rubrics)

2. Host reviews batch → codewalk_submit_batch_findings(session_id, [...]) → saved to disk as JSON; a Markdown companion is also written for easy reading

3. codewalk_review_next_batch(session_id) → next batch (context window is clean)

4. Repeat until all batches done

5. codewalk_get_review_summary(session_id) → structured summary of raw findings + verdict guidance (request_changes if any BLOCKING finding, else approve)

6. User edits llm_findings.json in the session folder → sets user_verdict to accepted / rejected per finding

7. codewalk_accept_and_verify_fix(session_id) returns the accepted findings → the host applies them with its own editing tools, then verifies with codewalk_run_static_analysis + codewalk_run_tests

8. (Optional) codewalk_re_review(target_branch=...) → fresh review that hides previously rejected findings

Finding shape for codewalk_submit_batch_findings:

An empty findings list is valid (means the batch is clean).

Review & approve fixes (agent + MCP)

1. Agent runs codewalk_run_review (returns enriched context for the host LLM to review)

2. Agent reviews each batch and calls codewalk_submit_batch_findings

3. After all batches: codewalk_get_review_summary

4. User edits llm_findings.json: set user_verdict to accepted or rejected for each finding

5. Apply + verify accepted fixes: codewalk_accept_and_verify_fix(session_id) returns every accepted finding with instructions — the host LLM applies them with its own editing tools, then verifies with codewalk_run_static_analysis + codewalk_run_tests. Codewalk never edits files over MCP.

Example: @codewalk review my changes against main, then fix each issue only after I approve

Natural-language prompts (review)

"Review my changes for bugs"

Tool: codewalk_run_review — requires an explicit target (see table above)

@codewalk review my changes
@codewalk review my local work
@codewalk_run_review target_branch="current"
@codewalk_run_review target_branch="main"
@codewalk_run_review staged=true target_branch="main"

When to use: Before pushing a PR. Codewalk gathers the full diff, neighborhood context, blast radius, and stack signals, then returns them so the host model can perform the review directly — no separate LLM inside codewalk.

"I've addressed the feedback — review again"

Tool: codewalk_re_review

@codewalk I've addressed the feedback — review it again against main
@codewalk_re_review target_branch="main"

Starts a fresh session and hides findings you previously rejected.

"Summarize / status of the review"

@codewalk summarize the review findings
@codewalk_get_review_summary <session_id>

@codewalk what's the status of that review session?
@codewalk_get_review_details <session_id>

"Apply the fixes I accepted"

@codewalk apply and verify the fixes I accepted
@codewalk_accept_and_verify_fix <session_id>

Then the host applies accepted findings and runs:

@codewalk run static analysis on the files I just changed
@codewalk_run_static_analysis <paths>

@codewalk run the tests
@codewalk_run_tests <paths>

Review quick reference

Prompt cheat sheet (all tools): MCP_EXAMPLES.md.

Install

Python 3.10+.

git clone https://github.com/gupta29470/codewalk-review.git
cd codewalk-review
python -m venv .venv && source .venv/bin/activate
pip install -e .
# or: pip install -r requirements.txt && pip install -e . --no-deps

Dev tooling:

pip install -e ".[dev]"
# or: pip install -r requirements-dev.txt
pre-commit install

MCP setup

Copy mcp.json.example into your host’s config and set cwd to the repo you want analyzed.

{
  "mcpServers": {
    "codewalk": {
      "command": "python",
      "args": ["-m", "codewalk.mcp.server"],
      "cwd": "/absolute/path/to/the/repo/you/want/to/analyze"
    }
  }
}

Use the venv’s python if the host won’t see your PATH. Every tool also accepts an optional repo_path to override cwd.

One repo per MCP server process. Codewalk keeps runtime state (graph, repo path) in memory. Pointing the same running MCP server at multiple repos — or rapidly switching workspaces in the same process — can overwrite that state. Use one editor window / one MCP connection per repo. The stdio transport is safe because each connection spawns a separate process.

Typical usage

Analyze / ask about structure

1. Graph builds automatically on first query (or call codewalk_analyze_codebase).

2. Ask things like: overview, blast radius of a file, circular deps, reading order, call chain.

3. Optional once per repo: codewalk_get_stack_info → agent saves stack via codewalk_save_stack_context for richer overviews and better review rubrics.

Review changes — see Code Review above.

Tools (25)

MCP tools — index / graph requirements

Configuration

Optional. Missing config = defaults.

• codewalk.yaml — excludes/includes, language overrides, static-analysis and test commands. Generate a starter with codewalk_generate_config.

• .codewalkignore — gitignore syntax; merged with .gitignore.

• .codewalk/stack_context.json — optional host-written stack metadata (richer overview + better review rubrics).

Example codewalk.yaml:

indexing:
  exclude:
    - tests/**
    - docs/**
    - "*.generated.*"
  include:
    - docs/architecture/**

For language/framework-specific review rubrics, place .md files in .codewalk/rubrics/ (e.g. .codewalk/rubrics/python.md, .codewalk/rubrics/python_fastapi.md, .codewalk/rubrics/core.md). These override built-in rubrics.

Adding .codewalk/ to .gitignore

Codewalk stores graph and review data inside each target repo at .codewalk/. This directory should not be committed:

# Codewalk index (auto-generated)
.codewalk/

Development

pytest                      # coverage via pyproject addopts
ruff check src tests
ruff format src tests
mypy --strict src/codewalk
pre-commit run --all-files

CI runs on Python 3.10–3.12 (lint, format, mypy, pytest with ≥90% coverage).

What this is not

• Not a knowledge-graph / docs / PDF indexer

• Not a vector / embedding search engine

• Not a hosted API — no auth, no multi-tenant server

• Does not call LLMs or edit your files over MCP

License

MIT (see pyproject.toml)