codewalk

Prerequisites: Python 3.10+.

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

Upgrading

To pull the latest code and reinstall:

cd /path/to/codewalk-review
git pull
pip install -e .
# or with dev tools:
pip install -e ".[dev]"

Then restart the MCP server in your host (Cursor, VS Code, Claude Desktop) so the new version is loaded.

MCP setup

codewalk is a stdio MCP server: the host (Cursor, VS Code, Claude Desktop) starts it as a subprocess and talks to it over stdin/stdout. You never run it as a long-lived service yourself — the host manages the process.

1. Get the absolute python path

The host GUI does not see your shell's venv, so always point command at the venv's python directly:

cd /path/to/codewalk-review && source .venv/bin/activate
which python        # e.g. /Users/you/Development/codewalk-review/.venv/bin/python

2. Cursor

Cursor's documented STDIO fields are command, args, env, and envFile — not cwd (docs). Do not rely on cwd; Cursor may ignore it and the process can start in $HOME, which makes codewalk try to scan your home directory.

Create .cursor/mcp.json in each workspace (the repo root you open in Cursor), e.g. MyApp/.cursor/mcp.json. Typically local / gitignored — it usually embeds an absolute path to your codewalk venv. One file per repo keeps the default root correct when you switch projects.

mkdir -p .cursor   # from the workspace / repo root

Use a shell wrapper so the server's process cwd is ${workspaceFolder} (Cursor interpolates that in args):

{
  "mcpServers": {
    "codewalk": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "cd \"${workspaceFolder}\" && exec /Users/you/Development/codewalk-review/.venv/bin/python -m codewalk.mcp.server"
      ]
    }
  }
}

Replace the python path with your venv from step 1. ${workspaceFolder} is the project that contains this .cursor/mcp.json.

Select the workspace MCP (required):

1. Cmd+Shift+P → open Customize / search MCP (or open the Plugins/MCPs UI).

2. Click the MCPs chip.

3. Open the leftmost workspace dropdown and under Workspaces select your repo name (e.g. MyApp) — not User / Team.

4. Add or confirm codewalk there (New MCP Server if needed). That edits the workspace .cursor/mcp.json, not a user-global config.

• Start: Cursor auto-starts the server when it loads the config. With the correct workspace selected under MCPs, codewalk should show green with its tools listed.

• List the tools from the CLI/chat: cursor-agent mcp list-tools codewalk — quick way to confirm the server is up and see all 25 tools.

• Stop/restart: MCPs UI → toggle codewalk off/on (with your workspace selected). Restart after editing the config or upgrading codewalk (git pull && pip install -e .) — the host does not reload it automatically.

• If it shows red: the command path is wrong or deps aren't installed in that venv. Test manually: /Users/you/Development/codewalk-review/.venv/bin/python -m codewalk.mcp.server should start and wait silently on stdio (Ctrl+C to quit).

3. VS Code

Create .vscode/mcp.json in the workspace (note: the key is servers, not mcpServers). VS Code supports variable substitution, so cwd can be ${workspaceFolder} — this makes the file safe to commit and share:

{
  "servers": {
    "codewalk": {
      "command": "/Users/you/Development/codewalk-review/.venv/bin/python",
      "args": ["-m", "codewalk.mcp.server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

• ${workspaceFolder} resolves to the folder you opened — codewalk will analyze that repo. (Multi-root workspaces: use ${workspaceFolder:name}.)

• The command python path still must be absolute — there is no variable that points into your codewalk venv.

• Start: Cmd+Shift+P → "MCP: List Servers" → select codewalk → Start Server. VS Code also auto-starts it on first Copilot Chat use of an MCP tool.

• Stop/restart: same menu → Stop Server / Restart Server. Restart after config edits or codewalk upgrades.

• Requires the Copilot Chat extension with MCP support enabled.

4. Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), same mcpServers shape as Cursor, then fully quit and relaunch Claude Desktop (it only reads the config at startup).

mcp.json.example contains both key variants — copy it and delete the one your host doesn't use.

Notes

• Default repo = nearest .git ancestor of the MCP process cwd, else the cwd itself. Set that via the host (cwd in VS Code; shell cd wrapper for Cursor) or pass optional repo_path on any tool call.

• First query / codewalk_analyze_codebase builds the intelligence graph (can take a while on a big repo); later queries reuse .codewalk/graph.duckdb. Progress is not streamed mid-build — the host should tell the user the graph is building before a cold or forced rebuild. To force a rebuild: codewalk_refresh_analysis, or delete the repo's .codewalk/ directory and restart the server.

• Reset/uninstall: remove the server block from the host config, restart the host, and delete .codewalk/ in the target repo. Nothing else is written outside the codewalk checkout.

• 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)