<p align="center">
  <h1 align="center">CODEWALK</h1>
   <p align="center" style="font-size:1.5em; font-weight:700;">
     <a href="https://www.codewalk.xyz/">Landing page & docs →</a>
   </p>
  <p align="center">
    <strong>AI-powered codebase intelligence tool</strong><br>
    <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
  </p>
</p>

**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.

<p align="center">
  <a href="#how-it-works">How it works</a> •
  <a href="#-demo">Demo</a> •
  <a href="#-code-review--powered-by-the-intelligence-layer">Code Review</a> •
  <a href="#install">Install</a> •
  <a href="#mcp-setup">MCP Setup</a> •
  <a href="#typical-usage">Usage</a> •
  <a href="#tools-25">Tools</a> •
  <a href="#configuration">Configuration</a> •
  <a href="#development">Development</a>
</p>

---

## 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.

---

## 🎬 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

| Capability | CodeRabbit / GitHub Copilot Review | Codewalk Review |
|---|---|---|
| **Architecture awareness** | ❌ No dependency graph | ✅ DuckDB + igraph: PageRank, fan-in, cycles, bottlenecks |
| **Blast radius** | ❌ | ✅ "This file has 23 callers — review with extra care" |
| **Works without indexing** | — | ✅ Just needs a git repo (graph enhances but isn't required) |
| **Batched for large PRs** | Dumps everything at once | ✅ Token-bounded batches, sorted by risk, host LLM stays focused |
| **Custom rubrics** | Limited | ✅ Per-language + per-framework + optional stack context |
| **Fix application** | Suggests only | ✅ Accept/reject → host applies → verify with tests |
| **Severity levels** | varies | `blocker` · `error` · `suggestion` |

### 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:

| Component | Auto (graph-only) |
|-----------|-------------------|
| Git diff + file content | ✅ |
| Rubrics + stack detection | ✅ (from file extensions / optional stack context) |
| Blast radius, PageRank, cycles | ✅ Built on-the-fly (~5s), then from cached DuckDB |
| Neighborhood (callers, related files) | ✅ From the graph |

### Severity levels

| Level | Value | Meaning |
|-------|-------|---------|
| **Blocker** | `"blocker"` | Must fix before merge — blocks the PR |
| **Error** | `"error"` | Should fix — real bugs, logic errors, security risks |
| **Suggestion** | `"suggestion"` | Nice to have — style, naming, minor improvements |

### 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.

| You want | Pass |
|---|---|
| Local work on this branch (staged + unstaged + untracked) | `target_branch="current"` |
| Commits + uncommitted work vs a base branch | `target_branch="main"` (or `develop`, …) |
| Staged only | `staged=True` |
| One commit | `commit="<sha>"` |

### 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`:

| Field | Required | Notes |
|-------|----------|-------|
| `severity` | ✅ | `'blocker'` \| `'error'` \| `'suggestion'` |
| `category` | ✅ | `'bug'` \| `'security'` \| `'style'` \| `'test'` \| `'blast_radius'` \| `'design'` \| `'naming'` \| `'complexity'` \| `'error_handling'` \| `'type_safety'` \| `'architecture'` \| `'logging'` \| `'privacy'` \| `'hygiene'` |
| `file_path` | ✅ | Path relative to repo root |
| `title` | ✅ | Short finding title |
| `explanation` | ✅ | Why it matters |
| `line_number` | | Optional |
| `current_code` | | Optional |
| `recommended_code` | | Optional |
| `blocking` | | Bool, default `false` |

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

| You want to... | Just say... |
|---|---|
| Review local work on this branch | `@codewalk review my local work` → `codewalk_run_review(target_branch="current")` |
| Review vs a base branch | `@codewalk review my changes against main` → `codewalk_run_review(target_branch="main")` |
| Review staged only | `@codewalk review staged changes against main` → `staged=True` |
| Re-review after fixes | `@codewalk review again against main` → `codewalk_re_review` |
| Accept/reject findings | Edit `llm_findings.json` → set `user_verdict` |
| Apply accepted fixes | `@codewalk apply and verify fixes` → `codewalk_accept_and_verify_fix` → host applies + verifies |
| Run static analysis | `@codewalk run static analysis on src/auth.py` |
| Run tests | `@codewalk run tests for src/auth.py` |

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

---

## Install

Python 3.10+.

```bash
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:

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

### Upgrading

To pull the latest code and reinstall:

```bash
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.

| Host | Config location / key |
|---|---|
| Cursor | workspace `.cursor/mcp.json` → `mcpServers` |
| VS Code | `.vscode/mcp.json` → `servers` |
| Claude Desktop | `claude_desktop_config.json` → `mcpServers` |

### 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:

```bash
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](https://cursor.com/docs/mcp)). 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.

```bash
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`):

```json
{
  "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:

```json
{
  "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](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](#-code-review--powered-by-the-intelligence-layer) above.

## Tools (25)

| Category | Tools |
|---|---|
| Setup | `codewalk_analyze_codebase`, `codewalk_refresh_analysis`, `codewalk_generate_config` |
| Query | `codewalk_get_module_info`, `codewalk_explain_function`, `codewalk_explain_class`, `codewalk_lookup_symbol`, `codewalk_get_overview`, `codewalk_get_blast_radius_map`, `codewalk_find_circular_dependencies`, `codewalk_get_reading_order`, `codewalk_get_execution_flow` |
| Architecture | `codewalk_get_architecture_health`, `codewalk_call_chain` |
| Stack | `codewalk_get_stack_info`, `codewalk_save_stack_context` |
| Review | `codewalk_run_review`, `codewalk_re_review`, `codewalk_review_next_batch`, `codewalk_submit_batch_findings`, `codewalk_get_review_summary`, `codewalk_get_review_details`, `codewalk_accept_and_verify_fix` |
| Maintenance | `codewalk_run_static_analysis`, `codewalk_run_tests` |

### MCP tools — index / graph requirements

| Tool | Graph required? | Notes |
|------|-----------------|-------|
| `codewalk_analyze_codebase` | Builds/loads | Persistent DuckDB graph |
| `codewalk_generate_config` | No | Creates starter `codewalk.yaml` |
| Query tools (overview, modules, symbols, …) | Yes | Auto-builds/loads graph |
| `codewalk_find_circular_dependencies` | Yes | Uses graph data |
| `codewalk_get_architecture_health` | Yes | Graph stats + cycles |
| `codewalk_run_review`, `codewalk_re_review`, `codewalk_get_stack_info` | Soft / Yes | Better with graph; review builds graph on demand |
| `codewalk_get_review_details` | Session on disk | Reads persisted session |
| `codewalk_accept_and_verify_fix` | Session on disk | Returns accepted findings; host applies them itself |
| `codewalk_run_static_analysis` | No | ruff/mypy/eslint/etc. |
| `codewalk_run_tests` | No | pytest/npm test/etc. |

## 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`:

```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:

```gitignore
# Codewalk index (auto-generated)
.codewalk/
```

## Development

```bash
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`)