English · 简体中文 · Usage Guide · Design · Benchmarks · Changelog

Tests License PyPI downloads GitHub stars

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

CodeWiki wiki page

CodeWiki graph explorer

• 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.
• Install the bundled Codex skill so Codex can plan, write, validate, and export source-grounded wiki pages from local CodeWiki evidence.
• 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.

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.

codewiki repos add . --name my-repo
codewiki analyze .
codewiki graphrag build . --embeddings
codewiki wiki catalog .
codewiki wiki pages .
codewiki skill install codex
codewiki wiki plan . --json
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 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 lite agents install . --target all
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. codewiki lite agents install can write Codex CLI and Claude Code MCP config plus agent instructions for the project.

CodeWiki ships a Codex-ready skill for agent-written wiki pages. It installs to $CODEX_HOME/skills/codewiki, or ~/.codex/skills/codewiki when CODEX_HOME is not set, and includes compact evidence and standalone HTML export helpers:

codewiki skill install codex
codewiki wiki plan . --language en --json
codewiki wiki evidence overview . --language en --limit 5 --json
cat overview.md | codewiki wiki save overview . --language en --title "Overview" --stdin --json
codewiki wiki validate overview . --language en --json

This workflow does not call CodeWiki's external LLM-backed wiki generator. Codex reads bounded source evidence, writes Markdown with CodeWiki source citations, saves it into the normal wiki store, and validates the saved page before export or publication.

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"

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

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

MIT