Metadata-Version: 2.4
Name: nc-codewiki
Version: 2.1.1
Summary: Transform codebases into comprehensive documentation using AI-powered analysis
Author: CodeWiki Contributors
License: MIT
Project-URL: Homepage, https://github.com/dandydarshan/CodeWiki
Project-URL: Repository, https://github.com/dandydarshan/CodeWiki
Project-URL: Issues, https://github.com/dandydarshan/CodeWiki/issues
Project-URL: Upstream, https://github.com/FSoft-AI4Code/CodeWiki
Keywords: documentation,code-analysis,ai,llm,developer-tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: GitPython>=3.1.40
Requires-Dist: Jinja2>=3.1.6
Requires-Dist: tree-sitter>=0.25
Requires-Dist: tree-sitter-language-pack<0.9.0,>=0.8.0
Requires-Dist: tree-sitter-python>=0.23.6
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.21.4
Requires-Dist: tree-sitter-typescript>=0.21.2
Requires-Dist: tree-sitter-c>=0.21.4
Requires-Dist: tree-sitter-cpp>=0.23.4
Requires-Dist: tree-sitter-c-sharp>=0.23.1
Requires-Dist: tree-sitter-php>=0.23.0
Requires-Dist: tree-sitter-kotlin>=1.1.0
Requires-Dist: tree-sitter-ruby>=0.23.1
Requires-Dist: tree-sitter-scala<0.24.0,>=0.23.2
Requires-Dist: tree-sitter-rust<0.24.0,>=0.23.2
Requires-Dist: openai>=1.107.0
Requires-Dist: litellm>=1.77.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: pydantic-ai>=1.0.6
Requires-Dist: google-genai>=1.36.0
Requires-Dist: requests>=2.32.4
Requires-Dist: truststore>=0.10.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: pathspec>=0.12.1
Requires-Dist: rich>=14.1.0
Requires-Dist: networkx>=3.5
Requires-Dist: psutil>=7.0.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: mermaid-parser-py>=0.0.2
Requires-Dist: fastapi>=0.116.0
Requires-Dist: uvicorn>=0.35.0
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: colorama>=0.4.6
Requires-Dist: logfire>=4.1.0
Requires-Dist: mcp<2,>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./img/black-background-logo.png">
    <img src="./img/white-background-logo.png" alt="CodeWiki" width="560">
  </picture>
</p>

<p align="center">
  <strong>Repository-level documentation for large codebases, written by AI agents from the dependency graph.</strong>
</p>

<p align="center">
  <a href="https://python.org/"><img alt="Python version" src="https://img.shields.io/badge/python-3.12+-blue?style=flat-square" /></a>
  <img alt="Version" src="https://img.shields.io/badge/version-2.1.0-blue?style=flat-square" />
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" /></a>
  <a href="https://github.com/FSoft-AI4Code/CodeWiki/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/FSoft-AI4Code/CodeWiki/ci.yml?branch=main&style=flat-square&label=CI" /></a>
  <a href="https://aclanthology.org/2026.findings-acl.288/"><img alt="Paper: Findings of ACL 2026" src="https://img.shields.io/badge/paper-Findings%20of%20ACL%202026-b31b1b?style=flat-square" /></a>
  <a href="https://github.com/FSoft-AI4Code/CodeWiki/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/FSoft-AI4Code/CodeWiki?style=flat-square" /></a>
</p>

<p align="center">
  <a href="#quick-start"><strong>Quick start</strong></a> •
  <a href="#whats-new-in-21"><strong>What's new in 2.1</strong></a> •
  <a href="#features"><strong>Features</strong></a> •
  <a href="#benchmark-results"><strong>Benchmark</strong></a> •
  <a href="./guides/README.md"><strong>Guides</strong></a> •
  <a href="https://aclanthology.org/2026.findings-acl.288/"><strong>Paper</strong></a>
</p>

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

<p align="center">
  📚 <strong>CodeWiki documents itself.</strong> Browse the documentation it generated for this repository at
  <a href="https://fsoft-ai4code.github.io/CodeWiki/docs/index.html">CodeWiki docs</a>.
</p>

<p align="center">
  <img src="./img/framework-overview.png" alt="CodeWiki framework" width="600" style="border: 2px solid #e1e4e8; border-radius: 12px; padding: 20px;"/>
</p>

---

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 16 languages. Then you can ask questions about the
code, answered from those docs and the code itself, in the docs site, the
terminal or your IDE. It needs an LLM API key, or a Claude or Codex
subscription, or an AI IDE that speaks MCP.

## Quick start

**1. Install**

```bash
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**

```bash
# 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, Google (Gemini API and Vertex AI),
Atlas Cloud, and Codex are also supported. See [Providers and models](./guides/providers.md).

**3. Generate**

```bash
cd /path/to/your/project
codewiki generate                     # writes ./docs/
codewiki generate --github-pages      # also writes an HTML viewer
codewiki generate --techdocs          # also exports a Backstage TechDocs site to ./techdocs
codewiki generate --update            # later: refresh after code changes
```

**4. Ask**

```bash
codewiki serve                        # docs site with an "Ask AI" chat, on localhost
codewiki ask "where is the signature verified?"
```

## What's new in 2.1

Full list in the [CHANGELOG](./CHANGELOG.md).

- **Ask AI.** `codewiki serve` serves the docs with a chat window that answers
  from the docs and the code, with citations down to the line. The GitHub
  Pages site's chat uses it too. `codewiki ask` answers in the terminal, and
  the MCP server gains no-LLM search, read, impact and status tools for IDE
  agents. [Guide](./guides/ask-ai.md)
- **Concurrent agents.** Module agents run side by side (`--concurrency`,
  default 4), with live progress and an ETA.
- **Nothing dropped silently on large repositories.** Each prompt carries the
  module's neighbourhood instead of the whole repository's component list.
  A module too big for one prompt splits further, and files that still don't
  fit are listed for the agent to read in full. Prompt budgets follow the
  model's context window (`--max-context-tokens`, or learned from provider
  errors). Parent pages are written from summaries each child page leaves.
- **Cost reporting.** Every run records tokens and cost per call in
  `metadata.json`, priced with `codewiki config pricing`.
- **Safer docs folders.** Generation says which branch and files it documents,
  `--update` backs up uncommitted docs first, the dependency graph is smaller
  and reusable across branches, and generated files collapse in pull requests.
- Also: a CLI that starts in 0.08 s, Mermaid validation that never leaves your
  machine, an XSS fix in the docs viewer, security scanning, and many fixes
  for Windows.

## 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](./CHANGELOG.md).

- **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](./guides/artifact-aware-generation.md)
- **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](./guides/incremental-updates.md)
- **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](./guides/mcp-ide-mode.md)
- 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, Dart (Flutter-aware), Go, Zig, Vue (single-file
components).

**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, several at once (`--concurrency`). Parent pages are
written from child pages. Diagrams are validated locally before they are
saved.

**Ask AI.** `codewiki serve` adds a chat to the docs site, `codewiki ask`
answers in the terminal, and IDE agents get search, read, impact and status
tools over MCP. Answers come from the docs and the current code, with
citations. [Guide](./guides/ask-ai.md)

**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.
`--no-cache` rebuilds from scratch; a plain run resumes, reusing existing pages.
`--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.**

```bash
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](./guides/cli-reference.md).

**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)
```

Commit all of it, `temp/` included: the saved graph lets `--update` on other
branches and machines reuse the docs. See
[incremental updates](guides/incremental-updates.md#what-to-commit).

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.

`--techdocs` (or `codewiki techdocs` on existing docs) also writes a
[Backstage TechDocs](https://backstage.io/docs/features/techdocs/) project,
`./techdocs/mkdocs.yml` plus `./techdocs/docs/`, with `overview.md` as
`index.md` and the module tree as the navigation. See
[Backstage TechDocs](./guides/backstage-techdocs.md).

This repository's own output is checked in under [`./docs/`](./docs/).

## Benchmark results

Evaluated on [CodeWikiBench](https://github.com/FSoft-AI4Code/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.

| Repository | Language | LoC | DeepWiki | CodeWiki 1.0 | CodeWiki 2.0 | 2.0 vs 1.0 |
| --- | --- | ---: | ---: | ---: | ---: | ---: |
| OpenHands | Python | 229,909 | 74.12 | 83.31 | **83.53** | +0.22 |
| svelte | JavaScript | 124,576 | 69.83 | 73.21 | **80.09** | +6.88 |
| puppeteer | TypeScript | 136,302 | 65.57 | 84.16 | **85.04** | +0.88 |
| ml-agents | C# | 86,106 | 75.74 | 80.92 | **89.35** | +8.43 |
| logstash | Java | 117,485 | 56.31 | 59.42 | **77.85** | +18.43 |
| Wazuh | C | 1,446,730 | 69.91 | 65.38 | **88.14** | +22.76 |
| Electron | C++ | 184,234 | 43.92 | 42.12 | **71.59** | +29.47 |
| **Average** | | | 65.06 | 69.79 | **82.23** | **+12.44** |

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.

| Topic | Requirements | DeepWiki | CodeWiki 1.0 | CodeWiki 2.0 |
| --- | ---: | ---: | ---: | ---: |
| Architecture | 128 | 72.95 | 78.02 | **82.00** |
| Functionality | 211 | 61.62 | 70.46 | **88.65** |
| Operations | 63 | 67.71 | **78.24** | 78.10 |
| Build and deployment | 27 | 62.84 | 28.16 | **71.90** |
| Security | 29 | 48.73 | 64.91 | **83.20** |
| Testing | 12 | 61.43 | 41.93 | **63.25** |
| Performance | 16 | 43.33 | 49.06 | **70.90** |

<p align="center">
  <img src="./img/benchmark-2.0.png" alt="Graph growth and score by stage" width="900"/>
</p>

<p align="center"><em>
(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.
</em></p>


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

| | |
| --- | --- |
| [CLI reference](./guides/cli-reference.md) | every command and flag |
| [Providers and models](./guides/providers.md) | API keys, Atlas Cloud, Azure, Bedrock, subscription mode |
| [Artifact-aware generation](./guides/artifact-aware-generation.md) | what gets documented beyond code, and how to tune it |
| [Incremental updates](./guides/incremental-updates.md) | how `--update` works, thresholds, the update record |
| [Ask AI](./guides/ask-ai.md) | `codewiki serve`, `codewiki ask`, and the MCP question tools |
| [MCP / IDE-driven mode](./guides/mcp-ide-mode.md) | Cursor, Claude Desktop, Claude Code, CodeBuddy |
| [Backstage TechDocs](./guides/backstage-techdocs.md) | publish the docs in a Backstage developer portal |
| [Development guide](./guides/development.md) | layout, pipeline, adding a language, tests, releasing |
| [Docker setup](./guides/docker.md) | the web application in a container |
| [CodeWikiBench](https://github.com/FSoft-AI4Code/CodeWikiBench) | the benchmark |
| [Live demo](https://fsoft-ai4code.github.io/codewiki-demo/) | generated documentation examples |

## Citation

CodeWiki was introduced in *CodeWiki: Evaluating AI's Ability to Generate
Holistic Documentation for Large-Scale Codebases*, published in
[Findings of ACL 2026](https://aclanthology.org/2026.findings-acl.288/).
If you use CodeWiki in your research, please cite:

```bibtex
@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

<p align="center">
  <a href="https://star-history.dera.page/#FSoft-AI4Code/CodeWiki&type=Date">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=FSoft-AI4Code/CodeWiki&type=Date&theme=dark" />
     <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=FSoft-AI4Code/CodeWiki&type=Date" />
     <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=FSoft-AI4Code/CodeWiki&type=Date" />
   </picture>
  </a>
</p>

## Sponsors

CodeWiki is proudly sponsored by **FPT Software**.

<p align="center">
  <a href="https://fptsoftware.com/en">
    <img src="./img/fpt-logo.svg" alt="FPT Software" width="220" />
  </a>
</p>

## License

MIT. See [LICENSE](./LICENSE).
