# Codewalk

> AI-powered codebase onboarding tool — point it at any repo and ask questions about the code. Uses tree-sitter parsing, RAG, and local LLMs.

- **Type:** MCP server
- **Install:** `agentstack add mcp-gupta29470-codewalk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gupta29470](https://agentstack.voostack.com/s/gupta29470)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gupta29470](https://github.com/gupta29470)
- **Source:** https://github.com/gupta29470/codewalk
- **Website:** https://codewalk.xyz

## Install

```sh
agentstack add mcp-gupta29470-codewalk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

CODEWALK
   
     Landing page & docs →
   
  
    AI-powered codebase intelligence tool
    Point it at any repo → understand the entire codebase in hours, not weeks
  

  Features •
  Demo •
  Frontend •
  Local Setup •
  Cloud •
  MCP •
  API •
  Architecture •
  Contributing

---

## What is Codewalk?

Codewalk analyzes any codebase and gives you:

- **Module detection** — groups files into logical modules automatically
- **Dependency graph** — extracts every import/require → builds the full dependency map
- **Blast radius** — "if I change this file, what breaks?"
- **Reading order** — optimal file reading sequence (dependencies first)
- **Execution flow** — entry points, module-to-module and file-to-file dependency flow
- **AI chat** — ask anything about the code, powered by RAG + tool-calling agent
- **Code review** — review git diffs for bugs, security issues, and style (context-enriched, OWASP-focused)
- **Incremental reindex** — re-embed only changed files using content hash comparison
- **Graph intelligence** — DuckDB + igraph: symbol-level call graph, cycle detection, centrality analysis, import chain tracing
- **Corrective RAG** — distance-based chunk filtering + LLM answer grading + query rewriting for higher quality answers
- **Voice interface** — talk to your codebase hands-free: mic → transcribe → Copilot routes → speak answer

Three ways to use it locally, plus optional cloud indexing:

| Interface | Best for |
|-----------|----------|
| **Web UI** (Next.js) | Visual exploration — Knowledge Graph UI, diagrams, module browser, blast radius viewer |
| **MCP Server** | VS Code Copilot, Claude Code, Cursor — AI agents use tools directly |
| **REST API** | Scripts, CI/CD, custom integrations |

**Cloud (optional):** Push to GitHub → [Codewalk Cloud](https://api.codewalk.xyz) indexes on the server → MCP downloads the index and queries **locally**. See [Cloud Deployment](#-cloud-deployment).

> **🎙️ Voice** is available via both **MCP** (`codewalk_voice_ask` + `codewalk_speak`) and **REST API** (`POST /voice/ask`) — ask questions by speaking, hear answers read aloud.

---

## Why Codewalk?

| Scenario | How Codewalk helps |
|----------|-------------------|
| **New dev joins the team** | Point Codewalk at the repo → get an overview, module map, and reading order. Self-onboard in hours instead of weeks of "hey, can you explain this?" |
| **LLM token costs are high** | Without RAG, the LLM needs your entire codebase in context — slow and expensive. Codewalk embeds code into a vector DB and retrieves only the relevant chunks per query. Faster answers, fraction of the tokens. |
| **Senior dev switches modules** | You know the auth module but now need to work on payments. Get module info, blast radius, and execution flow without bugging the payments team. |
| **Before a refactor** | Check blast radius before touching shared code. "If I change `base_model.py`, what breaks?" — get the answer before you break prod. |
| **PR reviews** | Run `codewalk_run_review` (MCP) or `POST /review` (API) — automated multi-stage review with OWASP security checks, blast radius warnings, and team guidelines matching. MCP mode returns enriched context so the calling model (Claude/GPT) performs the review directly — no separate LLM needed. |
| **Documentation is outdated** | Codewalk analyzes the *actual code*, not stale wiki pages. Always up to date. |

---

## 🔬 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 (3-5 per batch, grouped by feature)
         → Host LLM reviews each batch with full context
         → Submit findings to disk per batch (context stays clean)
         → Final summary: all findings + verdict
```

### 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 | ✅ 3-5 files per batch, sorted by risk, host LLM stays focused |
| **Custom rubrics** | Limited | ✅ Per-language + per-framework + team guidelines |
| **Fix application** | Suggests only | ✅ Accept/reject → apply atomically → verify with tests |
| **Severity levels** | varies | `blocker` · `error` · `suggestion` |

### Works without indexing

Review runs on **any git repo** — no `codewalk_analyze_codebase` needed. The intelligence layer enhances it when available:

| Component | Without index | With index (after analyze) |
|-----------|--------------|---------------------------|
| Git diff + file content | ✅ | ✅ |
| Rubrics + team guidelines | ✅ | ✅ |
| Stack detection | ✅ (from file extensions) | ✅ (cached) |
| Risk annotations | ⚠️ Diff-size proxy | ✅ PageRank, fan-in, cycles |
| Neighborhood (callers, tests) | ⚠️ Empty | ✅ From DuckDB graph |
| Blast radius warnings | ⚠️ Not available | ✅ Transitive impact |

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

### MCP review flow

1. `codewalk_run_review(target_branch='main')` → session + first batch
2. Host reviews batch → `codewalk_submit_batch_findings(session_id, [...])` → saved to disk
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 for final verdict
6. User accepts/rejects → `codewalk_finding_verdict` → `codewalk_apply_accepted`

### API review flow

```bash
curl -X POST http://localhost:8000/review \
  -H "Content-Type: application/json" \
  -d '{"target_branch": "master"}'
```

Runs: static analysis → batch review (parallel LLM) → dedup → verify → cluster → rank → verdict.

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔍 **Module Detection** | Auto-groups files into packages/modules by directory structure |
| 🕸️ **Dependency Graph** | Parses imports across 15+ languages via tree-sitter |
| 💥 **Blast Radius** | BFS on reversed dependency graph → shows transitive impact of any change |
| 📖 **Reading Order** | Topological sort → "read config.py before embedder.py because embedder imports config" |
| 🔄 **Execution Flow** | Entry points, module/file dependency chains, D3/ELK diagrams |
| 🤖 **AI Chat** | LangGraph agent with 7 tools, multi-turn conversation with memory |
| 🔎 **Semantic Search** | ChromaDB vector search on embedded code chunks (RAG) |
| 🔬 **Code Review** | Multi-stage review pipeline: test coverage, blast radius, guidelines RAG, context-enriched deep analysis |
| 🔄 **Incremental Reindex** | Content hash comparison — only re-embeds changed files, skips unchanged |
| 🧩 **MCP Server** | 42 MCP tools for VS Code Copilot / Claude Code / Cursor / Codex |
| 🎙️ **Voice Interface** | Talk to your codebase — mic recording, local STT (faster-whisper), agent-driven routing (MCP + API), TTS response |
| 🔬 **Graph Intelligence** | DuckDB persistent graph + igraph C-speed traversal: cycle detection, centrality, import chain tracing |
| 🧬 **Corrective RAG** | Distance-based chunk filtering (free) + LLM answer grading + query rewriting for reliable answers |
| 📦 **Parent-Child Chunking** | Full functions stored as parents, sub-chunks searched — retrieve complete context on match |
| ⚡ **Parallel Embedding** | Producer-consumer pipeline — CPU chunking overlaps with GPU embedding |
| 🏗️ **Multi-Provider LLM** | Ollama (local), OpenAI, Anthropic, Groq, Gemini, OpenRouter, DeepSeek |
| 📚 **Doc Indexing** | Index team docs (.md, .pdf, .txt) — search and ask questions with source citations |
| 🔄 **Reflection** | Actor→Critic→Improve loop used by deep research to refine cross-cutting reports |
| 🧑‍💻 **Human-in-the-Loop** | Approval gate before any code/file modification — LangGraph checkpoint + interrupt |
| 🔬 **Deep Research** | Fan-out parallel search → merge → synthesize → reflect for complex cross-cutting questions |
| 🏗️ **Architecture Health** | Graph stats, bottleneck files (betweenness centrality), PageRank, cycle detection with fix suggestions |
| 🌐 **15+ Languages** | Python, JS, TS, Java, Go, Rust, Ruby, PHP, C#, C++, C, Dart, Kotlin, Swift, YAML |

### Supported Languages

| Language | Extensions | Tree-sitter Parsing | Import Extraction |
|----------|-----------|---------------------|-------------------|
| Python | `.py` | ✅ | ✅ |
| JavaScript | `.js`, `.jsx` | ✅ | ✅ |
| TypeScript | `.ts`, `.tsx` | ✅ | ✅ |
| Java | `.java` | ✅ | ✅ |
| Go | `.go` | ✅ | ✅ |
| Rust | `.rs` | ✅ | ✅ |
| Ruby | `.rb` | ✅ | ✅ |
| PHP | `.php` | ✅ | ✅ |
| C# | `.cs` | ✅ | ✅ |
| C++ | `.cpp` | ✅ | ✅ |
| C | `.c` | ✅ | ✅ |
| Kotlin | `.kt` | ✅ | ✅ |
| Swift | `.swift` | ✅ | ✅ |
| Dart | `.dart` | ✅ *(optional install)* | ✅ |
| YAML | `.yaml`, `.yml` | — | — |
| JSON | `.json` | — | — |
| TOML | `.toml` | — | — |
| Markdown | `.md` | — | — |

> **Tree-sitter parsing** = extracts functions, classes, and methods for accurate chunking and function explanations.  
> **Import extraction** = builds the dependency graph, blast radius, and reading order.  
> Languages without tree-sitter support still get indexed via text splitting — they work with semantic search and AI chat, just without function-level granularity.

---

## 🆚 Codewalk vs. alternatives

Codewalk is **not another AI autocomplete**. It is a codebase intelligence layer: it builds a persistent dependency graph, embeds your code, indexes your docs, and exposes that intelligence through a UI, an MCP server, and an API.

If you need deep cross-file reasoning, blast-radius analysis, or AI review inside your existing IDE agent, Codewalk fits where general-purpose assistants stop.

| Use case | Typical approach | What Codewalk does differently |
|---|---|---|
| **Explain this codebase** | Ask a generic chat model and paste files | Builds a live graph + RAG so answers are grounded and cite real files |
| **PR review** | Lint + human review | LLM review with blast-radius, architecture, and custom guidelines |
| **Refactor shared code** | Grep for imports | Dependency graph + blast radius showing transitive impact |
| **Onboard a new developer** | Read wiki pages | Reading order + module map generated from actual code |
| **Team knowledge** | Search Confluence/Notion | Index docs alongside code and ask with citations |
| **AI agent tooling** | Write custom scripts or prompts | 42 MCP tools the agent can call directly |

---

## 🎬 Demo

### Web UI

https://github.com/user-attachments/assets/1bc99516-b3f6-4059-b463-de3c72bc850e

### MCP with VS Code Copilot

https://github.com/user-attachments/assets/a1dfd347-1135-47d2-b01d-3d995d86208e

### REST API

> 🎥 **[Video coming soon]**

### Voice Interface

https://github.com/user-attachments/assets/51d41d48-970f-437e-8c50-e6a104d71e0e

---

## 🖥️ Frontend — Knowledge Graph UI

Codewalk ships with a Next.js frontend for visual codebase exploration.

### What you can do

- **Structural view** — explore the repo as a layered dependency graph: modules, files, classes, and functions laid out as an interactive path flow.
- **Knowledge view** — semantic graph of entities and relationships surfaced by the AI analysis.
- **Path Finder** — pick a source and target node and discover import/dependency paths between them.
- **Search** — fuzzy + semantic search across files, symbols, and concepts.
- **Blast Radius / Diff mode** — visually highlight changed and affected nodes.
- **Themes** — switch between presets (Dark Gold, Dark Ocean, Dark Forest, Dark Rose, Light Minimal), accent colors, and heading fonts; your choice is saved locally.
- **Info Panel** — unified node details, metrics, source preview, and project overview.
- **KineticShell navigation** — index-dependent tabs stay locked until `GET /index-status` reports `indexed: true`.
- **Cloud Admin** — visit `/admin` to register repos, list repos, trigger indexing, copy tokens, and check server health/version.

### Run it

#### Quick start from a target repo

If you already have the Codewalk repo cloned elsewhere, run the combined launcher from the repo you want to explore:

```bash
/path/to/codewalk/scripts/run-ui-for-repo.sh
```

This starts the API from your current directory (discovering `codewalk.yaml`) and the frontend from the Codewalk checkout, automatically setting `CODEWALK_REPO_PATH` so the UI reads `.codewalk/` from your repo.

#### Frontend-only development

```bash
cd frontend
npm install
npm run dev
```

If you change frontend code and see stale chunk 404s or client-side exceptions, restart with a clean build cache:

```bash
npm run dev:clean      # clears .next and starts fresh
npm run restart        # kills port 3000 and restarts dev
# or
./scripts/restart-frontend.sh
```

Set `NEXT_PUBLIC_API_URL` to point at the backend (e.g. `http://localhost:8000` or `https://api.codewalk.xyz`).

Then open `http://localhost:3000`, analyze a repo, and click **Knowledge Graph**.

### Demo

> 🎥 **[Video coming soon — add frontend walkthrough here]**

---

## ⚙️ Setup (local)

> **Production cloud server?** See **[FULL_SETUP_GUIDE.md](FULL_SETUP_GUIDE.md)** — step-by-step: Hetzner, `api.codewalk.xyz`, GitHub App, webhooks, MCP download.

### Prerequisites

| Tool | Version | Check |
|------|---------|-------|
| Python | 3.10+ | `python3 --version` |
| Node.js | 18+ | `node --version` |
| Git | Any | `git --version` |
| Ollama *(optional)* | Latest | `ollama --version` |

### 1. Clone the codewalk repo

```bash
git clone https://github.com/gupta29470/codewalk.git
cd codewalk
```

### 2. Backend setup in codewalk

```bash
# Create virtual environment
python3 -m venv .codewalk-env
source .codewalk-env/bin/activate    # macOS / Linux
# .codewalk-env\Scripts\activate     # Windows

# Install Python dependencies
pip install -r requirements.txt
```

⚠️ VPN / Corporate Network / Private Network Issues

If you're behind a **VPN, corporate proxy, or private network**, package installations and model downloads may fail due to blocked connections or SSL certificate errors.

**Recommended: Use a normal (non-VPN) network for first-time setup.**

Codewalk's setup downloads packages from PyPI, npm, and HuggingFace. These are one-time downloads — once installed, everything runs locally. If possible:

1. **Disconnect from VPN** temporarily
2. Run the setup steps (`pip install`, `npm install`, start the backend once to download the embedding model)
3. **Reconnect to VPN** — everything is cached locally, no more downloads needed

> After the first run, Codewalk works fully offline (with Ollama). The VPN/corporate network won't cause any issues.

Optional: Dart/Flutter support (tree-sitter-dart)

```bash
# If you get an SSH error, run this first:
git config --global url."https://github.com/".insteadOf "git@github.com:"

# Then install:
pip install "tree-sitter-dart @ git+https://github.com/UserNobody14/tree-sitter-dart.git"
```

Without this, Codewalk still works — Dart files just won't get tree-sitter parsing (falls back to text splitting).

### 3. Frontend setup in codewalk

```bash
cd frontend
npm install
cd ..
```

### 4. Configure environment in codewalk

Copy the template: `cp env.local.example.txt .env` then edit:

```env
# ─── LLM Configuration ──────────────────────────────────────
# Provider: ollama | openai | anthropic | gemini | gro

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gupta29470](https://github.com/gupta29470)
- **Source:** [gupta29470/codewalk](https://github.com/gupta29470/codewalk)
- **License:** MIT
- **Homepage:** https://codewalk.xyz

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gupta29470-codewalk
- Seller: https://agentstack.voostack.com/s/gupta29470
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.