Codewalk

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

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:

/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

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:

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 [FULLSETUPGUIDE.md](FULLSETUPGUIDE.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

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

2. Backend setup in codewalk

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

# 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

cd frontend
npm install
cd ..

4. Configure environment in codewalk

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

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