CodeWiki

简体中文 | Usage Guide | Changelog

CodeWiki is a single-user code intelligence platform for AST-based repository analysis, GraphRAG retrieval, source-grounded wiki generation, and LiteLLM-powered Q&A.

Screenshots

Highlights

• Analyze Python, TypeScript/TSX, JavaScript/JSX, Java, Go, Rust, C, C++, and C#.
• Build deterministic code graphs for imports, definitions, calls, routes, inheritance, source references, and configuration usage.
• Generate DeepWiki-style catalogs and pages with source citations, diagrams, translations, incremental updates, and browser-side exports.
• Ask GraphRAG-grounded questions through the Web UI, CLI, HTTP API, or MCP server.
• Use Lite Mode for a project-local, no-LLM graph index optimized for AI agent context, traces, impact analysis, and MCP tools.
• Use SQLite by default, or PostgreSQL with full-text search and optional pgvector vector search.

Quick Start

Install from PyPI:

pip install codewiki
codewiki serve

Open http://127.0.0.1:8000, register a repository, run analysis, then generate a wiki or ask questions.

Run with Docker Compose:

docker compose up --build

The packaged Python app includes the built frontend. A source checkout is only needed for development or Docker-based local runs.

Common Commands

codewiki repos add . --name my-repo
codewiki analyze .
codewiki graphrag build . --embeddings
codewiki wiki catalog .
codewiki wiki pages .
codewiki ask --repo my-repo "How does the main workflow fit together?"
codewiki mcp

Most repository arguments accept an id, id prefix, registered name, path, or Git URL. Use --json for machine-readable output.

Lite Mode

Lite Mode creates a project-local .codewiki/codewiki-lite.sqlite3 index and skips LLM, Wiki, GraphRAG chunk, and Web UI workflows. It is intended for local AI assistants that need fast symbol search, source context, call traces, and affected-file analysis.

codewiki lite index .
codewiki lite query AuthService
codewiki lite context "how authentication works"
codewiki lite trace LoginForm createSession
codewiki lite callers generate_page
codewiki lite affected src/auth.py
codewiki mcp --lite --path .

codewiki lite status reports pending file changes. codewiki lite sync refreshes the index, and codewiki lite watch keeps it fresh with a polling watcher. MCP Lite Mode catches up an existing index on startup unless --no-sync is passed.

Configuration

CodeWiki defaults to SQLite:

CODEWIKI_DATABASE_URL=sqlite+aiosqlite:///./data/codewiki.sqlite3

PostgreSQL is also supported:

CODEWIKI_DATABASE_URL=postgresql+psycopg://codewiki:codewiki@localhost:5432/codewiki

Configure LLM profiles with codewiki config or .env:

codewiki config
codewiki config --set CODEWIKI_LLM__DEFAULT__MODEL=openai/gpt-4.1
codewiki config --profile qa --model openai/gpt-4.1 --api-key "$OPENAI_API_KEY"

Documentation

• Usage Guide: installation, Docker, database setup, wiki workflow, LLM profiles, CLI, MCP, HTTP API, and supported languages.
• Design Notes: architecture and feature design.
• PostgreSQL Compatibility Design: storage compatibility, PostgreSQL FTS, and pgvector design.
• Benchmarking Guide and Benchmark Report: benchmark workflow and current results.
• Changelog: release history.

Development

make install
make start
make lint
make typecheck
make test
make build

Default local URLs:

• Backend: http://127.0.0.1:8000
• Frontend: http://127.0.0.1:5173

Python Typing

Python type checking uses mypy with a gradual configuration in pyproject.toml. New public service, repository, API helper, and CLI helper functions should include explicit parameter and return types. Prefer dataclasses, Pydantic models, TypedDict, or Protocol over broad dict[str, Any] when data crosses module boundaries. Keep Any near integration edges such as LLM JSON payloads, SQLAlchemy JSON columns, and third-party parser output.

License

MIT