nc-codewiki 2.0.2

Repository-level documentation for large codebases, written by AI agents from the dependency graph.

Quick start • What's new in 2.0 • Features • Benchmark • Guides • Paper

https://github.com/user-attachments/assets/951d5d3c-fd6e-4734-8b16-445d880f95d3

📚 CodeWiki documents itself. Browse the documentation it generated for this repository at CodeWiki docs.

CodeWiki reads a repository, builds its dependency graph, splits the graph into a hierarchy of modules, and has agents write one page per module plus an overview, with Mermaid diagrams. It works on codebases from a few thousand to over a million lines, in 11 languages. It needs an LLM API key, or a Claude or Codex subscription, or an AI IDE that speaks MCP.

Quick start

1. Install

pip install nc-codewiki          # or: uv tool install nc-codewiki
codewiki --version

Prebuilt wheels are published for Windows x86_64, Linux x86_64 and macOS (universal2: Apple Silicon and Intel) on Python 3.12–3.14.

Needs Python 3.12+, Git, and Node.js with npm at install time.

2. Pick a provider

# Any OpenAI-compatible endpoint (OpenAI, LiteLLM proxy, OpenRouter, ...)
codewiki config set \
  --provider openai-compatible \
  --api-key YOUR_API_KEY \
  --base-url https://api.example.com/v1 \
  --main-model claude-sonnet-4 \
  --cluster-model claude-sonnet-4

# Or: no API key, run on your Claude Code subscription (`claude login` first)
codewiki config set --provider claude-code \
  --main-model claude-sonnet-4-6 --cluster-model claude-sonnet-4-6

Anthropic, Azure OpenAI, AWS Bedrock, Atlas Cloud, and Codex are also supported. See Providers and models.

3. Generate

cd /path/to/your/project
codewiki generate                     # writes ./docs/
codewiki generate --github-pages      # also writes an HTML viewer
codewiki generate --update            # later: refresh after code changes

What's new in 2.0

The documentation an agent can write is bounded by what the dependency graph contains. 2.0 makes that graph more complete, wider, and keeps it current. Full list in the CHANGELOG.

• More complete dependency graphs. Free functions become documentation units, so C code and function-centric C++, Java, and C# packages are no longer nearly empty. Call resolution in C, C++, Java, and C# is scope-, namespace-, include-, and import-aware. Library calls are filtered by an external symbol table. Ruby and Scala analyzers were added.
• Artifact-aware generation. Build files, CI workflows, Dockerfiles, package manifests, packaging scripts, configuration, and schemas become graph nodes with edges to the code they reference. They are clustered and documented like code, with a guaranteed Build, Deployment and Configuration module when clustering drops them. Guide
• Component-level incremental updates. codewiki generate --update diffs the saved graph against the current code, repairs the module tree, and sends one agent per affected module to patch its page and the pages that describe it. Everything else is left untouched. On svelte, one update after one commit cost $0.34 against $21.48 for a full build. Guide
• Subscription mode. Run on a Claude Pro/Max or Codex subscription through the claude and codex CLIs, with no API key.
• MCP server for IDE agents. codewiki mcp exposes the analysis toolchain to Cursor, Claude Desktop, Claude Code, or CodeBuddy. The IDE's own model does the writing. Guide
• Also: Atlas Cloud provider, prompt caching, .gitignore handling, Kotlin and PHP analyzers, a CI workflow, a security policy.

Features

Languages. Python, Java, JavaScript, TypeScript, C, C++, C#, Kotlin, PHP, Ruby, Scala, Rust.

Hierarchical decomposition. The dependency graph is clustered into a module tree, recursively, so a 1.4M-line repository gets the same treatment as a 10k-line one. Depth and size thresholds are configurable.

Recursive agents. One agent per leaf module reads the code through tools and writes the page. Parent pages are written from child pages. Diagrams are validated before they are saved.

Artifacts are documented. On by default. --no-artifacts gives the 1.x behaviour, --with-prose also reads README and docs/, --artifact-exclude skips generated configuration trees.

Incremental updates. --update refreshes only what changed. --compare-to <commit> sets the base commit for CI and squashed merges. If too much changed, it falls back to a full build and says so.

Customization.

codewiki generate --include "*.cs" --exclude "Tests,Specs,*.test.cs"
codewiki generate --focus "src/core,src/api" --doc-type architecture
codewiki generate --instructions "Focus on public APIs and include usage examples"
codewiki generate --language ja                    # write the docs in Japanese
codewiki config agent --exclude "Tests,Specs"      # make it the default

--language takes a code or a name (ja, Japanese, vi, zh, ...). Page text, headings and diagram labels follow it. Filenames and module names stay ASCII so links keep working, and the viewer shows the translated page titles. --update reuses the language the docs were generated in.

--include replaces the default file set. --exclude merges with the built-in ignore list. Every flag is in the CLI reference.

IDE-driven mode. Add {"command": "codewiki", "args": ["mcp"]} to your IDE's MCP servers and ask the agent to document the repository. No LLM configuration in CodeWiki.

Output

./docs/
├── overview.md                  # start here
├── <module>.md ...              # one page per top-level module
├── <module>/<sub-module>.md ... # sub-module pages, in folders mirroring the module tree
├── module_tree.json             # the module hierarchy
├── first_module_tree.json       # clustering result before super-grouping
├── metadata.json                # model, version, commit, statistics
├── update_record.json           # every decision of the last --update run
├── temp/artifact_index.json     # artifact files by class
├── temp/dependency_graphs/      # the saved graph (used by --update)
└── index.html                   # viewer (with --github-pages)

Pages mirror the module tree: a module's page sits next to the folder holding its sub-modules (auth.md, auth/login.md). --flat puts every page in ./docs instead, which helps small models that get relative links wrong. --update keeps the layout the docs were generated with.

This repository's own output is checked in under ./docs/.

Benchmark results

Evaluated on CodeWikiBench: seven repositories, 486 rubric requirements, the same LLM judge for every system. Scores are weighted rubric scores from 0 to 100. DeepWiki and CodeWiki 1.0 were re-run under the same setting as 2.0 (September 2026), so the numbers differ from the ones in the paper.

The gain is largest where the 1.0 graph missed the most structure (C, C++, Java, C#) and near zero where the analyzers did not change (Python, JavaScript, TypeScript). Artifacts lift the build and testing topics, which 1.0 could not see at all.

(a) how much the 2.0 code graph grew over 1.0; (b) nodes and edges added by artifacts; (c) score by stage. "Conference version" is CodeWiki 1.0, "C1 + C2" is CodeWiki 2.0.

Requirements

• Python 3.12+
• Node.js and npm at install time (a dependency builds against them)
• Git
• One of: an LLM API key, a Claude Code or Codex subscription, or an MCP-capable AI IDE

Guides

Citation

CodeWiki was introduced in CodeWiki: Evaluating AI's Ability to Generate Holistic Documentation for Large-Scale Codebases, published in Findings of ACL 2026. If you use CodeWiki in your research, please cite:

@inproceedings{hoang-etal-2026-codewiki,
    title = "{C}ode{W}iki: Evaluating {AI}{'}s Ability to Generate Holistic Documentation for Large-Scale Codebases",
    author = "Hoang, Anh Nguyen and Le-Anh, Minh and Le, Bach and Bui, Nghi D. Q.",
    booktitle = "Findings of the {A}ssociation for {C}omputational {L}inguistics: {ACL} 2026",
    month = jul,
    year = "2026",
    address = "San Diego, California, United States",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2026.findings-acl.288/",
    doi = "10.18653/v1/2026.findings-acl.288",
    pages = "5812--5827",
}

Star history

Sponsors

CodeWiki is proudly sponsored by FPT Software.

License

MIT. See LICENSE.