codewiki

Generate deep, traceable codebase wiki documentation — citation tracking, knowledge graph, Mermaid diagrams, incremental updates. Cross-client (OpenCode / Claude Code / Codex / Qoder).

What it does

codewiki scans your codebase and generates a structured wiki documentation system with:

• Interactive HTML — single-file HTML with sidebar navigation, stats overview, file classification charts, document details. Open in any browser.
• Citation tracking — every document links back to source files with line numbers
• Knowledge graph — metadata.json with PARENT_CHILD / CALLS / IMPLEMENTS / EXTENDS / DEPENDS_ON relations
• Mermaid diagrams — graph, sequenceDiagram, erDiagram, flowchart, classDiagram
• Incremental updates — file-hash-based change detection, only rewrite affected docs
• Integrity verification — check citation reachability, section completeness, Mermaid syntax
• Cross-client — works with OpenCode, Claude Code, Codex, Qoder, Trae, Cursor

Inspired by Qoder's repowiki, with enhancements: incremental updates, verification, multi-language, cross-client support.

Quick start

Install

npm install -g @trapsea/codewiki

Generate

codewiki init                              # scan codebase, generate outline + metadata
codewiki gen                               # generate markdown document bodies (dispatch mapper agents)
codewiki verify-docs                       # verify docs and optionally fix mermaid issues
codewiki html                              # generate interactive HTML (open in browser)
codewiki refresh                           # incremental update on code changes
codewiki verify                            # verify citation, sections, diagrams
codewiki query "用户认证"                   # search generated docs

Or just run the default bootstrap flow:

codewiki                                   # init + prompt next steps

Output structure

.ai/
├── codewiki/                      # markdown docs root
│   ├── INDEX.md
│   ├── 项目概述.md
│   ├── 架构设计/
│   └── ...
├── meta/codewiki/                 # metadata root
│   ├── outline.json
│   ├── codewiki-metadata.json
│   ├── file-hash.json
│   ├── source-manifest.json
│   └── verify-report.json
└── codewiki.html                  # ⭐ interactive HTML (open in browser)

The codewiki.html is a single-file interactive document with:

• Sidebar — topic-grouped document tree, expandable/collapsible
• Overview — total docs, source files, code lines, modules, graph relations
• Charts — file classification bar chart, module file distribution
• Document details — cited files, source symbols, file detail table
• Dark theme — GitHub-inspired dark UI

Document template

Each generated document contains 10 standard sections:

1. 引言 / Introduction
2. 项目结构 / Project structure (Mermaid graph)
3. 核心组件 / Core components
4. 架构总览 / Architecture overview (Mermaid graph/sequence)
5. 详细组件分析 / Detailed component analysis (Mermaid sequence/flowchart)
6. 依赖分析 / Dependency analysis (Mermaid graph LR)
7. 性能考虑 / Performance considerations
8. 故障排查指南 / Troubleshooting guide
9. 结论 / Conclusion
10. 附录 / Appendix

Every section ends with "章节来源" citing source files with line numbers. Document header has <cite> block listing all referenced files.

See docs/template-spec.md for the full specification.

Cross-client support

codewiki works with any AI coding assistant. The install/ directory contains pre-configured command/agent/skill/rule files for each IDE.

Install to your IDE

Ask your AI assistant to read install.md and follow the instructions. The AI will copy the command/agent/skill/rule files to your IDE's global config directory.

前提：用户已执行 npm install -g @trapsea/codewiki，IDE 模板直接调用全局命令 codewiki。

OpenCode — /codewiki command, codewiki-mapper agent, codewiki skill

~/.config/opencode/command/codewiki*.md         ← commands
~/.config/opencode/agents/codewiki-mapper.md    ← agent
~/.config/opencode/skills/codewiki/SKILL.md     ← skill

Claude Code — /codewiki slash command, codewiki-mapper agent

~/.claude/commands/codewiki*.md
~/.claude/agents/codewiki-mapper.md

Cursor — codewiki rule

~/.cursor/rules/codewiki.mdc

Manual install

# OpenCode
npm install -g @trapsea/codewiki
mkdir -p ~/.config/opencode/{command,agents,skills/codewiki}
cp install/opencode/command/codewiki*.md ~/.config/opencode/command/
cp install/opencode/agents/codewiki-mapper.md ~/.config/opencode/agents/
cp install/opencode/skills/codewiki/SKILL.md ~/.config/opencode/skills/codewiki/

# Claude Code
npm install -g @trapsea/codewiki
mkdir -p ~/.claude/{commands,agents}
cp install/claude/commands/codewiki*.md ~/.claude/commands/
cp install/claude/agents/codewiki-mapper.md ~/.claude/agents/

# Cursor
mkdir -p ~/.cursor/rules
npm install -g @trapsea/codewiki
cp install/cursor/rules/codewiki.mdc ~/.cursor/rules/

CLI reference

codewiki [init|gen|html|verify-docs|refresh|verify|query] [options]

Commands:
  init      Scan codebase, generate outline + metadata skeleton
  verify-docs  Verify docs and optionally fix mermaid issues
  html      Generate interactive single-file HTML (open in browser)
  gen       Generate markdown document bodies (dispatch mapper agents)
  refresh   Incremental update based on file hash change detection
  verify    Verify citation, section, diagram integrity
  query     Search generated documents

Options:
  --help               Show help
  --version            Show version
  --module=<name>      Only generate for specified module
  --focus=<area>       Focus area (api|entity|service|config|arch|deploy|dev-guide)
  --fix                Auto-fix issues (verify command)

Programmatic API

import { cmdInit, cmdGen } from '@trapsea/codewiki';

// 直接使用默认配置执行初始化与生成
cmdInit({ project: 'my-project', modules: [] } as any, process.cwd());
cmdGen({ project: 'my-project', modules: [] } as any, process.cwd());

Comparison with Qoder repowiki

| Feature | Qoder repowiki | codewiki | |---|---|---| | Citation precision | file://path#L10-L50 | same + symbol-level FQN + git commit lock | | Knowledge graph | PARENT_CHILD | + CALLS / IMPLEMENTS / EXTENDS / DEPENDS_ON | | Diagrams | 4 Mermaid types | 6 Mermaid types | | Incremental update | none | file-hash-based | | Verification | none | 5 checks + report + optional auto-fix | | Multi-language | zh only | zh + en | | Index | none | INDEX.md navigation | | Cross-client | Qoder only | OpenCode + Claude + Codex + Qoder + Trae + Cursor | | Implementation | — | TypeScript (npm package) |

Requirements

• Node.js >= 18
• Git (for commit hash tracking)

License

MIT