FSoft-AI4Code/CodeWiki

CodeWiki – AI‑powered repository‑level documentation

What it is – CodeWiki is an open‑source Python framework that automatically generates holistic documentation for large codebases. It drives a multi‑agent LLM pipeline (OpenAI‑compatible, Anthropic, Azure, Bedrock, Atlas Cloud, or subscription‑mode Claude/Codex) to produce markdown text and visual artifacts (Mermaid diagrams, data‑flow charts, sequence diagrams) that describe functions, APIs, and cross‑module interactions.

Why it matters – Traditional doc generators work file‑by‑file and miss architectural context. CodeWiki’s three‑stage architecture (hierarchical decomposition → recursive multi‑agent processing → multi‑modal synthesis) lets it scale to projects of millions of lines while preserving the overall system view.

---

Key capabilities

Feature	What you get
Hierarchical decomposition	Dynamic‑programming‑style partitioning of a repo into modules and sub‑modules, keeping architectural relationships intact.
Recursive multi‑agent system	Adaptive agents delegate work to sub‑agents, enabling scalable, quality‑controlled generation across the whole repository.
Multi‑modal output	Markdown docs plus Mermaid‑compatible architecture, data‑flow, dependency, and sequence diagrams.
Multi‑language support	Python, Java, JavaScript, TypeScript, C, C++, C#, Kotlin, PHP, Ruby.
LLM‑agnostic	Works with any OpenAI‑compatible API, Anthropic, Azure OpenAI, AWS Bedrock, Atlas Cloud, or Claude/Codex subscription mode.
Incremental updates	Regenerate only changed modules (--update or --compare-to <commit>), useful for CI/CD.
Git‑aware file selection	Respects .gitignore by default; fine‑grained --include/--exclude patterns let you target specific files or skip tests.
Configurable token limits	Adjust context windows (--max-tokens, --max-token-per-module, etc.) to match the chosen model.
GitHub‑Pages ready	--github-pages creates an interactive HTML viewer and optional documentation branch.

---

Quick start (from the README)

# Install directly from the repo
pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git

# Verify
codewiki --version

# Configure an LLM provider (example: OpenAI‑compatible)
codewiki config set \
  --provider openai-compatible \
  --api-key $OPENAI_API_KEY \
  --base-url https://api.openai.com/v1 \
  --main-model gpt-4o \
  --cluster-model gpt-4o \
  --fallback-model claude-sonnet-4

# Generate docs for a project
cd /path/to/your/project
codewiki generate          # plain markdown output in ./docs/
codewiki generate --github-pages --create-branch   # HTML viewer + git branch

---

Output layout

./docs/
├─ overview.md          # high‑level repo overview
├─ <module>.md          # per‑module API and usage docs
├─ module_tree.json     # hierarchical structure used for generation
├─ first_module_tree.json
├─ metadata.json        # timestamps, model used, token stats
└─ index.html           # interactive viewer (when --github-pages is used)

The repository ships its own generated docs under ./docs/, so you can see a live example.

---

Evaluation

The authors introduced CodeWikiBench, a benchmark for repository‑level documentation quality. On 21 diverse repos (Python, JS/TS, Java, C#, C/C++), CodeWiki (using Claude‑Sonnet‑4) achieved an overall score of 68.79 %, beating the prior state‑of‑the‑art system DeepWiki by +4.73 %. Detailed per‑language and per‑repo tables are in the paper (arXiv 2510.24428).

---

Requirements & installation notes

• Python 3.12+ (runtime)
• Node.js – needed for Mermaid diagram validation
• Access to an LLM API (any of the supported providers) or a Claude/Codex subscription CLI
• Git – required for branch creation and for respecting .gitignore
• Optional Docker deployment (see docker/DOCKER_README.md)

---

License & provenance

• License: MIT (per LICENSE file)
• Sponsor: FPT Software (the project is part of the FSoft‑AI4Code research group)
• Academic reference:

@misc{hoang2025codewikievaluatingaisability,
  title={CodeWiki: Evaluating AI's Ability to Generate Holistic Documentation for Large-Scale Codebases},
  author={Anh Nguyen Hoang and Minh Le-Anh and Bach Le and Nghi D. Q. Bui},
  year={2025},
  eprint={2510.24428},
  archivePrefix={arXiv},
  primaryClass={cs.SE},
  url={https://arxiv.org/abs/2510.24428},
}

---

Bottom line

CodeWiki is a fully‑featured, research‑backed tool that lets developers and researchers turn massive, multi‑language codebases into readable, architecture‑rich documentation with a single CLI command, leveraging modern LLMs while giving fine‑grained control over models, token budgets, and file selection.