Introducing Codewalk: Open-Source Codebase Intelligence for Teams That Move Fast

I built Codewalk because I was tired of watching engineers spend their first month on a project reading stale wiki pages and asking "what breaks if I change this?" in Slack. I was also tired of AI coding assistants that could autocomplete a function but could not tell me whether a refactor was safe.

Codewalk is an open-source codebase intelligence layer. It analyzes any git repository, builds a dependency graph from real imports, embeds the code for semantic search, and exposes everything through a web UI, an MCP server, and a REST API. It is designed to answer architectural questions, surface risk before a refactor, review diffs with full context, and turn any codebase into something a new developer can understand in hours instead of weeks.

This post is a complete walkthrough of what Codewalk does, how it is built, why its code review is different from the closed-source alternatives, and how to run it on your own machine.

What codebase intelligence actually means

Most AI coding tools treat your repository as a pile of text. They chunk files, embed the chunks, and retrieve whatever seems relevant to the current prompt. That works for small questions like "what does this function do?" It fails for structural questions like "if I change this file, what breaks?" or "which files are the most important in this module?" or "what is the correct order to read this codebase?"

Codebase intelligence means building an explicit model of the system and making it queryable. The model includes:

• Files and modules — how the code is organized.
• Imports and dependencies — how files actually connect.
• Symbols and calls — functions, classes, methods, and who calls them.
• Risk signals — centrality, cycles, blast radius, change impact.
• Embeddings — semantic meaning of code for search and chat.

Codewalk combines all of these. The graph gives you structure. The embeddings give you semantics. The agent gives you a natural-language interface. The review layer gives you actionable feedback on diffs.

See all demos →

Every feature in Codewalk

Codewalk is not a single feature. It is a stack of tools that work together. Here is the complete list.

Core intelligence

• Module detection — automatically groups files into logical modules based on directory structure and import patterns.
• Dependency graph — extracts every import and require across 15+ languages via tree-sitter and builds the full dependency map.
• Blast radius — answers "if I change this file, what breaks?" with a BFS on the reversed dependency graph, showing direct and transitive impact.
• Reading order — produces a topological sort of files so you read dependencies first. "Read config.py before embedder.py because embedder imports config."
• Execution flow — traces entry points and module-to-module / file-to-file dependency chains, rendered as Mermaid diagrams.
• Graph intelligence — DuckDB persistent graph + igraph C-speed traversal: symbol-level call graph, cycle detection, centrality analysis, and import chain tracing.
• Architecture health — graph stats, bottleneck files via betweenness centrality, PageRank for the most important files, cycle detection with fix suggestions.

Search and chat

• Semantic search — ChromaDB vector search on embedded code chunks.
• AI chat — LangGraph agent with 11 tools, multi-turn conversation with memory.
• Corrective RAG — distance-based chunk filtering, LLM answer grading, and query rewriting for higher-quality answers.
• Parent-child chunking — full functions stored as parents, sub-chunks searched; retrieve complete context on a match.
• Symbol lookup — find every definition and key reference of a named symbol across the repo.
• Doc indexing — index team docs (.md, .pdf, .txt) and ask questions with source citations.

Code review

• Review without indexing — run a multi-stage review on any git repo using only the diff, changed files, static analysis, and team guidelines. No embedding step required.
• Architecture-aware review — when an index exists, review is enriched with PageRank, fan-in, cycles, blast radius, and caller context.
• Batched review — groups 3-5 files per batch, sorted by risk, so the host LLM stays focused and the context window stays clean.
• Custom rubrics — per-language, per-framework, and team guidelines from codewalk.yaml.
• Severity levels — blocker, error, suggestion.
• Human-in-the-loop fixes — accept or reject findings, apply fixes atomically, then verify with tests and static analysis.

Interfaces and integrations

• Web UI — Next.js frontend with Knowledge Graph UI, diagrams, module browser, blast radius viewer, and architecture health dashboard.
• MCP server — 41 tools for VS Code Copilot, Claude Code, Cursor, and OpenAI Codex.
• REST API — 35+ endpoints for analysis, chat, views, review, maintenance, and voice.
• Voice interface — talk to your codebase hands-free: mic → transcribe → route → speak answer. Available through MCP and the REST API.

Operations

• Incremental reindex — re-embed only changed files using content hash comparison; skips unchanged files.
• Refresh analysis — re-scan without re-embedding after code changes.
• Multi-provider LLM — Ollama, OpenAI, Anthropic, Groq, Gemini, OpenRouter, DeepSeek.
• Parallel embedding — producer-consumer pipeline where CPU chunking overlaps with GPU embedding.
• Static analysis runner — runs ruff, mypy, eslint, and language-appropriate linters.
• Test runner — auto-detects and runs pytest, npm test, go test, cargo test, and more.
• Cloud indexing — optional Hetzner deployment that indexes repos on push via GitHub App webhook; MCP downloads the index and queries locally.

Supported languages

Python, JavaScript, TypeScript, Java, Go, Rust, Ruby, PHP, C#, C++, C, Kotlin, Swift, Dart, YAML. Languages with full tree-sitter support get function-level chunking. Languages without tree-sitter support are still indexed via text splitting and work with semantic search and chat.

Why Codewalk's code review is better

The part of Codewalk I am most proud of is the review engine. It is built on top of the codebase intelligence layer, which means it does not just lint — it understands the architecture, knows which files are risky, and reviews with full context.

How the review pipeline 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
  → Re-review: hide rejected findings and verify fixes

The pipeline starts with the git diff. Static analysis runs. Stack detection identifies the language and framework from file extensions. The graph layer adds risk signals if an index exists. Files are batched into groups of 3-5 so the LLM can focus. Each batch is reviewed. Findings are persisted to disk. A final summary produces the verdict.

Works without indexing

This is the key difference. Review runs on any git repo. You do not need to run codewalk_analyze_codebase first.

Without an index, you get a solid review of the diff itself. With an index, you get senior-engineer-level context about architecture and risk. Most importantly, the review is never blocked by an embedding queue.

Comparison with alternatives

Severity levels

• Blocker — must fix before merge; blocks the PR.
• Error — should fix; real bugs, logic errors, or security risks.
• Suggestion — nice to have; style, naming, or minor improvements.

MCP review flow

1. codewalk_run_review() — creates a session and returns the first batch (reviews working-tree changes by default; pass target_branch='...' to diff against a branch).
2. The host LLM reviews the batch.
3. codewalk_submit_batch_findings(session_id, [...]) — saves findings to disk.
4. codewalk_review_next_batch(session_id) — returns the next batch.
5. Repeat until all batches are reviewed.
6. codewalk_get_review_summary(session_id) — produces a structured summary.
7. The user edits llm_findings.json to set user_verdict to accepted or rejected for each finding.
8. codewalk_apply_and_verify_fix(session_id) applies accepted fixes and runs static analysis + tests in one call.
9. codewalk_re_review() — starts a fresh review of working-tree changes; any finding marked rejected in the previous session is hidden from the summary.

API review flow

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

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

The architecture

Codewalk is built as a set of composable layers. Each layer does one thing and exposes its output to the next.

Ingestion layer

scanner.py enumerates files and computes content hashes. file_filter.py applies a deterministic safety net: it always skips .git, node_modules, dependency and build directories, binaries, media, secrets, lock files, and generated suffixes. tech_detect.py identifies language and framework signals.

Repo-specific exclusions live in codewalk.yaml:

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

Analysis layer

code_parser.py uses tree-sitter to extract functions, classes, methods, and imports across 15+ languages. dependency_graph.py turns imports into edges. module_detector.py auto-groups files into modules.

Graph layer

The graph is stored in DuckDB with a ten-table schema covering files, imports, symbols, symbol calls, chunks, modules, and module dependencies. DuckDB was chosen because it is fast, embeddable, and expressive for analytical queries.

For traversal-heavy operations, Codewalk loads the graph into igraph. This gives C-speed cycle detection, PageRank, betweenness centrality, and shortest-path queries.

Embedding layer

chunker.py splits code using parent-child chunking: full functions are stored as parents, and sub-chunks are searched. When a sub-chunk matches, the complete parent function is retrieved. embedder.py uses Jina Code Embeddings 1.5B. vector_store.py persists vectors in ChromaDB.

Agent layer

The chat agent is a LangGraph state graph with 11 tools. It uses Corrective RAG: distance-based chunk filtering, LLM answer grading, and query rewriting. If the retrieved context is not good enough, the query is rewritten and retried.

Review layer

The review layer parses diffs, runs static analysis, batches files by risk, and coordinates LLM review. Findings are persisted with finding_store.py and session_store.py. Approved fixes are applied safely with fix_applier.py.

Voice layer

The voice interface records audio, transcribes it locally with faster-whisper, routes the question to the right tool via the configured LLM, and speaks the answer with edge-tts.

The three interfaces

Codewalk exposes the same engine through three surfaces.

Web UI

The Next.js frontend is for visual exploration:

• Structural view: modules, files, classes, functions as a layered dependency graph.
• Knowledge view: semantic graph of entities and relationships.
• Path Finder: trace import paths between two nodes.
• Search: fuzzy + semantic search across files, symbols, and concepts.
• Blast Radius / Diff mode: highlight changed and affected nodes.
• Architecture health dashboard.
• Cloud admin panel at /admin.

See all demos →

MCP server

The MCP server exposes 41 tools to VS Code Copilot, Claude Code, Cursor, and OpenAI Codex. Examples:

@codewalk analyze this codebase
@codewalk what's the blast radius of base.py?
@codewalk show me the execution flow
@codewalk review my changes for target branch main
@codewalk find circular dependencies
@codewalk check architecture health
@codewalk voice_ask

Each MCP connection spawns a separate process, so repos stay isolated.

See all demos →

REST API

The FastAPI backend provides 35+ endpoints. Example:

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

Codewalk vs. alternatives

Codewalk is not another AI autocomplete. It is a codebase intelligence layer.

Compared to closed-source tools, Codewalk is inspectable, self-hostable, extensible, and free to try.

Local setup

Requirements: Python 3.10+, Node.js 18+, Git. Ollama is optional.

# 1. Clone
git clone https://github.com/gupta29470/codewalk.git
cd codewalk

# 2. Backend
python3 -m venv .codewalk-env
source .codewalk-env/bin/activate
pip install -r requirements.txt

# 3. Configure
cp env.local.example.txt .env
# Edit .env: LLM_PROVIDER, LLM_MODEL, embedding model, optional API keys

# 4. Start API
uvicorn src.codewalk.api.main:app --reload --port 8000

In another terminal:

cd frontend
npm install
npm run dev

Open http://localhost:3000.

To analyze and review a repo:

# From inside the target repo
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"index_mode": "auto"}'

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

Why open source

I believe codebase intelligence should be:

• Inspectable — you can see exactly what the graph contains.
• Self-hostable — run the whole stack on your own hardware.
• Extensible — add languages, reviewers, and tools without waiting for a vendor.
• Free to try — no credit card, no per-seat trial.

Codewalk is MIT licensed. The API, MCP server, web UI, and cloud deployment playbooks are all public.

What is next

The roadmap focuses on three areas:

1. Deeper graph intelligence — symbol-level call graphs, richer architecture health metrics, cross-repo reasoning.
2. Better agent collaboration — more MCP tools, better tool selection, tighter IDE integration.
3. Easier self-hosting — one-command deploys, managed cloud indexing, clearer team onboarding.

I am building this in public. If Codewalk sounds useful, star the repo and open an issue if something breaks.

• GitHub: github.com/gupta29470/codewalk
• Landing page: codewalk.xyz
• Docs: /docs
• Code review: /code-review
• Demos: /feature-demos