OpenWiki

Turn code repositories into bilingual Wikis that are readable, searchable, and connected by traceable relationships.

A pure Rust backend performs code analysis, AST graph construction, and vector indexing, while Next.js provides interactive reading, Q&A, research, slides, and workshops.

English · 简体中文

Quick Start · Core Capabilities · How It Works · Configuration · CLI, API, and MCP · Development

Why OpenWiki

Multiple repository sources: GitHub, GitLab, Bitbucket, read-only Docker-mounted directories, and browser folder uploads.
Analyze first, generate second: Rust and tree-sitter parse code natively. Even without a configured generation model, OpenWiki produces a baseline Wiki and code graph.
Explainable code relationships: Records containment, imports, calls, inheritance, source locations, and extraction confidence; supports node, neighbor, and shortest-path queries.
Code-aware Q&A: TurboVec semantic retrieval and graph neighborhoods jointly provide context; supports regular questions and up to five rounds of deep research.
Local persistence: Settings, project manifests, Wikis, graphs, vector indexes, slides, and workshops are stored under output/web/; uploaded or cloned repositories are stored in each project directory.
Multiple interfaces: A Next.js Web frontend plus Rust HTTP APIs, SSE, WebSocket, CLI, and MCP.

Quick Start

Docker Compose

Docker and Docker Compose are required. From the repository root, run:

docker compose -f docker/docker-compose.yml up -d --build

No .env file is required. After startup, open:

Service	URL
Web	http://localhost:3000
API	http://localhost:8001
Health check	http://localhost:8001/health

Generate your first Wiki:

Optional: open Model Settings in the top-right corner of the Web app and configure a generation model to enhance the Wiki. Configure chat and embedding models as well if you need Q&A.
Return to the home page and enter a remote repository URL, or choose Upload local repository. A private-repository token is used only for the current clone and is never written to project data.
Select the Wiki language and depth, then start generation. The page reports progress over SSE; when complete, you can browse the Wiki and code graph or export Markdown.

Without a generation model, OpenWiki keeps the baseline documentation generated by Rust. Without an embedding model, the Wiki remains available, but code Q&A does not.

See the Docker deployment guide for ports, mounts, host-model connectivity, and troubleshooting.

Core Capabilities

Category	Support
Repository sources	GitHub, GitLab, Bitbucket, restricted local paths, browser folder uploads
Wiki	Simplified Chinese / English; comprehensive / concise depth; Markdown / JSON export
Source languages	Python, JavaScript, TypeScript, Java, Kotlin, C#, C, C++, PHP
Code graph	File, symbol, and dependency nodes; containment, import, call, and inheritance relations; communities, neighbors, shortest paths
Retrieval and interaction	TurboVec 4-bit vector index with up to 20 semantic results; graph-enhanced Q&A, deep research, slides, and workshops
Generation models	OpenAI-compatible, Atlas Cloud, Anthropic, Azure OpenAI, AWS Bedrock, Claude Code CLI, Codex CLI
Chat models	OpenAI / OpenRouter / LiteLLM / DashScope-compatible APIs, Ollama, Azure, Google, AWS Bedrock
Embedding models	OpenAI / LiteLLM / DashScope-compatible APIs, Ollama, Google, AWS Bedrock Titan / Cohere
Interfaces	Web, HTTP API, SSE, WebSocket, CLI, MCP

The interface language and Wiki content language are independent. Both can be set to Chinese or English in the Web app.

Defaults and Limits

For local uploads, the browser first reads the path manifest and every .gitignore; the backend calculates an upload plan. Files matched by ignore rules or custom exclusions are not uploaded.
Remote repositories also apply .gitignore during analysis, followed by custom include and exclude rules.
Defaults: up to 20,000 uploaded files, 512 MiB total upload size, and 10,000 supported source files analyzed per project. Individual files larger than 2 MiB are skipped.
Wiki generation runs in the background. After a service restart, interrupted acquisition, analysis, generation, or indexing jobs are queued again.
Each model request times out after 600 seconds by default. If one page fails, OpenWiki keeps its baseline page and continues generating the others.
Q&A requires a ready vector index. When a code graph exists, graph neighborhoods are combined with semantic results; without a graph, retrieval falls back to semantic results only.

How It Works

flowchart LR
    A[GitHub / GitLab / Bitbucket] --> B[Acquire repository]
    U[Browser folder] --> F[.gitignore and custom filters]
    L[Read-only local mount] --> F
    B --> F
    F --> C[Rust source analysis]
    C --> G[tree-sitter code graph]
    C --> W[Bilingual Wiki]
    C --> E[Embeddings]
    E --> R[TurboVec index]
    G --> Q[Graph-enhanced retrieval]
    R --> Q
    W --> X[Web / export]
    Q --> X
    Q --> S[Q&A / research / slides / workshops]
    C --> P[(output/web/projects)]
    G --> P
    W --> P
    R --> P
    S --> P

The backend contains only two Rust crates:

openwiki-core: repository analysis, Wiki construction, tree-sitter code graphs, JSON storage, and TurboVec indexing.
openwiki-app: HTTP / SSE / WebSocket, model adapters, CLI, and MCP; builds to a single openwiki executable.

The production API image contains openwiki, Git, certificates, and OpenBLAS. It does not include a Python runtime.

Configuration

Model settings are best configured from Model Settings in the Web app. Generation, chat, and embedding models each support a provider, Base URL, API key, and model name.

API keys are sent only to the Rust backend. The Web app receives only configuration status and masked values. Settings persist at:

output/web/settings/models.json

On Unix, the settings directory uses mode 0700 and the file uses mode 0600. Treat output/ as sensitive data when backing it up or granting access.

Common Environment Variables

Variable	Default	Purpose
`OPENWIKI_LISTEN`	`0.0.0.0:8001`	API listen address
`OPENWIKI_DATA_DIR`	`output/web`	Root directory for settings and project data
`OPENWIKI_WEB_ORIGIN`	`http://localhost:3000`	Web origin allowed by the API
`OPENWIKI_LOCAL_REPO_ROOTS`	`/repos` (container)	Allowed local-repository roots
`OPENWIKI_REPOS_PATH`	`..` (Compose)	Host directory mounted read-only at `/repos`
`OPENWIKI_MODEL_TIMEOUT_SECONDS`	`600`	Timeout for one model request
`OPENWIKI_UPLOAD_MAX_FILES`	`20000`	Browser upload file limit
`OPENWIKI_UPLOAD_MAX_BYTES`	`536870912`	Browser upload byte limit
`OPENWIKI_ANALYSIS_MAX_FILES`	`10000`	Per-project analysis file limit
`OPENWIKI_HOST_GATEWAY`	`host.docker.internal`	Gateway used by containers to access host model services
`NEXT_PUBLIC_API_BASE_URL`	`http://localhost:8001`	API URL reachable by the browser
`WEB_PORT` / `API_PORT`	`3000` / `8001`	Ports exposed to the host by Compose

With Compose, you can enter a host model URL such as http://127.0.0.1:11434 directly in the Web app; the API container rewrites loopback hosts to OPENWIKI_HOST_GATEWAY. To provide initial model defaults for a fresh data volume, copy .env.web.example to .env. It lists optional model, repository, and request-limit variables, but it is not required for startup.

Data and Security

output/web/
├── settings/models.json
└── projects/<project-id>/
    ├── manifest.json
    ├── repository/
    ├── analysis.json
    ├── docs/wiki.json
    ├── graph/graph.json
    ├── rag/index.tvim
    ├── rag/chunks.json
    └── artifacts/
        ├── slides.json
        └── workshop.json

Project manifests and generated artifacts use atomic JSON replacement. Deleting or rebuilding containers does not remove the host output/ directory.
Browser upload paths must be relative. Path traversal and duplicate paths are rejected, while .git contents are removed.
/repos is read-only in Docker. Only canonical paths under OPENWIKI_LOCAL_REPO_ROOTS are accepted as local sources.
Remote repository URLs must be credential-free HTTP(S) URLs. Private-repository tokens are passed through a temporary Git request header and are also redacted from error output.
The code graph is saved as Graphify / NetworkX node-link-compatible JSON at graph/graph.json.

CLI, API, and MCP

CLI

Generate a baseline Wiki, analysis result, and code graph from a local repository without a model:

cd backend
cargo run -p openwiki-app -- generate \
  --repo /path/to/repository \
  --output /path/to/wiki \
  --language en \
  --wiki-mode comprehensive \
  --no-model

The output directory contains wiki.json, analysis.json, graph.json, overview.md, per-module Markdown files, and module trees. Other entry points:

cargo run -p openwiki-app -- config show --json
cargo run -p openwiki-app -- mcp
cargo run -p openwiki-app -- version

HTTP API

# Get job status
curl http://localhost:8001/api/jobs/<project-id>

# Get the complete code graph and statistics
curl http://localhost:8001/api/projects/<project-id>/graph
curl http://localhost:8001/api/projects/<project-id>/graph/stats

# Export the Wiki; format may be markdown or json
curl -OJ 'http://localhost:8001/api/projects/<project-id>/export?format=markdown'

Generation progress is available from GET /api/jobs/<project-id>/events over SSE. Q&A uses GET /api/projects/<project-id>/chat upgraded to WebSocket. The graph API also exposes node, neighbor, shortest-path, and query endpoints.

MCP

After building the release binary, register OpenWiki as an MCP stdio server:

{
  "mcpServers": {
    "openwiki": {
      "command": "/absolute/path/to/backend/target/release/openwiki",
      "args": ["mcp"]
    }
  }
}

MCP provides analyze_repo, generate_docs, read_code_components, documentation writing and editing, module-tree management, plus query_graph, get_node, get_neighbors, shortest_path, and graph_stats. analyze_repo returns a session ID, analysis and graph paths, language statistics, and graph statistics. See skills/openwiki-wiki-generator/SKILL.md for the complete workflow.

Development

Local development requires Rust 1.97.1, Node.js, and Git. Start the API and Web app separately:

# Terminal 1
cd backend
cargo run -p openwiki-app -- serve

# Terminal 2
cd web
npm ci
npm run dev

See the development guide for formatting, Clippy, tests, the 90% coverage gate, frontend verification, and design constraints. Issues and pull requests are welcome; before submitting code, run the checks relevant to your changes.

Acknowledgements

OpenWiki's research-oriented code-analysis approach originates from CodeWiki, and its Web interaction model is based on DeepWiki Open. The native Rust graph kernel independently implements a Graphify-compatible interchange format and does not include Graphify's Python source code or runtime.

Third-party Notices

See THIRD_PARTY_NOTICES.md for third-party components, copyrights, and licenses.

License

OpenWiki is released under the MIT License.

Name		Name	Last commit message	Last commit date
backend		backend
docker		docker
skills/openwiki-wiki-generator		skills/openwiki-wiki-generator
web		web
.dockerignore		.dockerignore
.env.web.example		.env.web.example
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
IDE_DRIVEN_GUIDE.md		IDE_DRIVEN_GUIDE.md
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md

Navigation Menu

Repository navigation

About

Repository files navigation

OpenWiki

Why OpenWiki

Quick Start

Docker Compose

Core Capabilities

Defaults and Limits

How It Works

Configuration

Common Environment Variables

Data and Security

CLI, API, and MCP

CLI

HTTP API

MCP

Development

Acknowledgements

Third-party Notices

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

OpenWiki

Why OpenWiki

Quick Start

Docker Compose

Core Capabilities

Defaults and Limits

How It Works

Configuration

Common Environment Variables

Data and Security

CLI, API, and MCP

CLI

HTTP API

MCP

Development

Acknowledgements

Third-party Notices

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages