Get started in minutes

Codewalk is open source and runs locally. Install the Python backend, start the API server, and analyze any repo from its working directory.

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

Quick Start

Clone Codewalk

Clone the open-source repo and create a Python virtual environment.

git clone https://github.com/gupta29470/codewalk.git
cd codewalk
python3 -m venv .codewalk-env

Install Dependencies

Install Python requirements. Configure LLM keys only if using a cloud provider.

source .codewalk-env/bin/activate
pip install -r requirements.txt
cp env.local.example.txt .env

Start the API

Run the FastAPI server on port 8000.

source .codewalk-env/bin/activate
uvicorn src.codewalk.api.main:app --reload --port 8000

Analyze a Repo

Run from inside the repo you want to analyze. The repo is discovered from cwd via codewalk.yaml.

cd /path/to/target-repo
curl -X POST http://localhost:8000/analyze -H "Content-Type: application/json" -d '{"index_mode":"auto"}'

Interface Options

Web UI

Visual dashboard for human exploration and architecture visualization. Start with npm install in the frontend/ directory.

MCP Server

38 tools inside VS Code Copilot, Claude Code, Cursor, and Codex CLI. Configure mcp.json and type @codewalk.

REST API

35+ FastAPI endpoints for analyze, chat, search, review, docs, and voice. Base URL: http://localhost:8000

Cloud Indexing

Indexing on your server. Query everywhere.

Codewalk is open source, so you can deploy the cloud component to your own infrastructure. Connect a GitHub App to your Codewalk server, push to any repo, and the server builds the index incrementally. Every team member downloads the index via MCP and queries it locally — no per-user embedding cost, no stale local indexes, no code leaving the team unless you want it to.

1. Deploy Codewalk server to your infra

2. Install GitHub App on the repo

3. Push triggers register + index

4. Server atomic-swaps the new index

5. Per-repo tokens secure downloads

6. MCP pulls index → local query

Because the index lives on your server, you can centralize compute for the team: one machine embeds, everyone else pulls and queries. The MCP client still runs locally, so actual code questions are answered on the user's laptop using the downloaded index.

MCP Tools

Codewalk exposes 38 tools through the Model Context Protocol. The AI agent (Copilot, Claude, Cursor) calls most of them automatically; a few are approval or voice steps for the human.

Setup & Query

Tool	What it does
codewalk_analyze_codebase	Scan, chunk, embed, and build the dependency graph in one call.
codewalk_get_overview	Project summary, tech stack, modules, riskiest files, and dependency diagram.
codewalk_search_codebase	Semantic code search over embedded chunks.
codewalk_lookup_symbol	Find definitions and references of a named function, class, or method.
codewalk_get_module_info	Inspect a module: files, languages, dependencies, blast radius.
codewalk_explain_function	AI explanation of what a function does.
codewalk_explain_class	AI explanation of what a class does.
codewalk_get_blast_radius_map	Files and modules affected by changing a target file or module.
codewalk_find_circular_dependencies	Detect import cycles and suggested fixes.
codewalk_get_reading_order	Optimal file reading sequence via topological sort.
codewalk_get_execution_flow	Module/file dependency chains and entry points.
codewalk_get_architecture_health	Graph stats, bottlenecks, PageRank, cycle detection.
codewalk_call_chain	Trace the shortest import path between two files.
codewalk_show_knowledge_graph	Export graph data for visualization.
codewalk_index_docs	Index team docs (.md, .pdf, .txt) into the vector store.
codewalk_search_docs	Search indexed team docs.
codewalk_ask_docs	RAG answer grounded in indexed docs with citations.

Review & Human-in-the-Loop

Tool	What it does
codewalk_run_review	Review git diff with architecture context and security checks.
codewalk_review_file	Run the full review pipeline on a single file.
codewalk_get_stack_info	Detect language/framework stack signals.
codewalk_get_review_details	Retrieve persisted findings for a review session.
codewalk_load_guidelines	Load team coding standards into the review context.
codewalk_finding_verdict	Accept or reject a review finding.
codewalk_apply_accepted	Apply all accepted findings from a session.
codewalk_approve_action	Human-in-the-loop approval gate; returns approval token.
codewalk_apply_fix	Apply a single fix using an approval token.
codewalk_verify_fix	Run static analysis and tests after applying fixes.

Maintenance

Tool	What it does
codewalk_generate_config	Create a stack-specific codewalk.yaml with sensible excludes.
codewalk_incremental_reindex	Re-embed only changed files using content hashes.
codewalk_refresh_analysis	Re-scan files and rebuild graph without re-embedding.
codewalk_run_static_analysis	Run ruff/mypy/eslint/etc. on given files.
codewalk_run_tests	Auto-detect and run pytest/npm test/etc. for given files.

Cloud & Voice

Tool	What it does
codewalk_pull_index	Download the latest index from your Codewalk server.
codewalk_connect_repo	One-step cloud setup for a repo.
codewalk_index_status	Compare local vs cloud index version.
codewalk_check_version	Server health and version check.
codewalk_voice_ask	Record voice, transcribe, and route to the right tool.
codewalk_speak	Speak a summary aloud via text-to-speech.

API Endpoints

Base URL: http://localhost:8000 (or your deployed Codewalk server).

Analysis

Method	Endpoint	Description
POST	/analyze	Index a codebase. Repo discovered from cwd via codewalk.yaml.
POST	/analyze/stream	Index a codebase with Server-Sent Events progress.
GET	/index-status	Check whether the current workspace is indexed.

Views, Chat & Search

Method	Endpoint	Description
GET	/overview	Project overview with tech stack, modules, and riskiest files.
GET	/modules	List all modules.
GET	/modules/{name}	Details for one module.
GET	/blast-radius	Top 15 riskiest files.
GET	/blast-radius/{module}	Blast radius for a module or file.
GET	/reading-order	Recommended reading order via topological sort.
GET	/execution-flow	Module/file dependency flow.
GET	/architecture	Architecture health: centrality, cycles, bottlenecks.
GET	/cycles	Circular dependencies.
POST	/chat	Ask the AI agent a question.
POST	/chat/stream	Streaming chat response.
POST	/semantic-search	Semantic search over embedded code chunks.
POST	/rag/expand-query	LLM query expansion for RAG.
POST	/rag/rerank	LLM chunk reranking.
POST	/rag/symbol-lookup	Symbol lookup via DuckDB.

Review & Voice

Method	Endpoint	Description
POST	/review	Review git diff. Works with or without an index.
POST	/review/stream	Review git diff with SSE progress.
POST	/review/cancel	Cancel a running review.
POST	/review/file	Review a single file.
POST	/review/guidelines	Load team coding guidelines.
POST	/review/verdict	Accept or reject a finding.
POST	/review/apply-accepted	Apply all accepted findings.
POST	/review/apply	Apply a single fix after approval.
POST	/voice/ask	Voice-in, voice-out Q&A.

Docs & Maintenance

Method	Endpoint	Description
POST	/docs/index	Index team docs.
POST	/docs/search	Search indexed docs.
POST	/docs/ask	Ask a question over indexed docs.
POST	/refresh	Re-scan without re-embedding.
POST	/incremental-reindex	Re-embed only changed files.
POST	/tools/static-analysis	Run ruff/mypy/eslint/etc.
POST	/tools/run-tests	Run pytest/npm test/etc.
POST	/chat/approve	Approve or reject an interrupted agent action.
POST	/research	Deep research over the codebase.
GET	/version	Codewalk version and commit info.
GET	/staleness	Local vs cloud index staleness.
GET	/health	Health check.

Common patterns

First-time setup

POST /analyze {"index_mode":"auto"}

Scans files, chunks, embeds, and builds the dependency graph. On subsequent runs, auto skips unchanged work.

Ask a question

POST /chat {"message":"Explain auth","thread_id":"t1"}

Multi-turn agent with memory. Answers cite real files and line numbers.

Review before merge

POST /review {"target_branch":"main"}

Works with or without an index. Returns severity, categories, and fix suggestions.

After code changes

POST /refresh then POST /incremental-reindex

Refresh rebuilds graph metadata without re-embedding. Incremental reindex only re-embeds changed files by content hash.

Next steps

Cloud Full Setup Guide Explore features