CodeWiki in Practice: Install Options, OAuth Risks, and Incremental Updates
When generating architectural documentation for large repositories, existing tools typically fall into one of two extremes: either piling up docstrings for isolated functions or forcing a full rebuild from scratch. In a repository like Svelte—roughly 125,000 lines of code—a single full run takes 2 hours and 46 minutes and costs $21.48.
FSoft-AI4Code’s CodeWiki (FSoft-AI4Code/CodeWiki) takes a different engineering route: it uses static analysis to extract deterministic components and dependency edges, delegates semantic module clustering and technical writing to agents, and introduces a component-level dependency graph diff in v2.0. According to benchmarks in the official incremental update guide, updating documentation for a single commit requires just 1.6% of the cost of a full build.
Yet deploying CodeWiki based solely on secondhand write-ups or outdated reports invites trouble. It is easy to conflate CodeWiki with Google’s identically named service (codewiki.google), install the v2.0.0 tag only to find the TechDocs flag missing, leave configuration parameters inflated tenfold, or run the Codex track with its sandbox disabled when enabling OAuth subscription passthrough on private repositories.
Based on the CodeWiki main branch source code (commit a1b9f4a) and the official incremental update guide, this article breaks down environment setup, the security boundaries across its three provider tracks, configuration calibration, and CI/CD incremental update practices.
Clarifying Version Coordinates and the Name Collision
Before installing, two fundamental reference points must be clarified: the name collision with Google’s service and the feature gap between the Git release tag and the main branch.
CodeWiki, the open-source project initiated by FSoft-AI4Code in June 2025, is completely unrelated to codewiki.google, which Google announced in November 2025 on the Google Developers Blog.
Popular Hacker News threads criticizing “documentation theater” were aimed squarely at Google’s hosted service. When evaluating open-source CodeWiki’s capabilities and constraints, engineers should base their decisions on its actual source code and the peer-reviewed benchmarks published in ACL 2026 Findings.
Licensed under MIT, CodeWiki requires Python 3.12+, Git, and Node.js during installation. When selecting an installation target, relying solely on the latest v2.0.0 tag (released on 2026-09-18) falls short, as several critical features exist only in unreleased commits merged into main after v2.0.0:
- Backstage TechDocs Export (
--techdocs): Generates MkDocs-compliant directory structures required by Spotify Backstage Internal Developer Portals (IDPs). This capability was merged intomainon November 5, 2026 (PR #155) and is absent from thev2.0.0tag. - Expanded Language Parsers: While the paper evaluated only 7 languages and the
v2.0.0README listed 11, themainbranch has expanded to 17 languages—with support for Vue, Rust, Dart/Flutter, Go, Zig, and Lean 4 currently existing only in unreleased commits.
IMPORTANT
Install from the main branch for TechDocs or Go/Rust support: If your team plans to integrate with Backstage TechDocs or your repositories contain Vue, Rust, Dart/Flutter, Go, Zig, or Lean 4, install directly from the repository head using pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git@main.
The Three-Track Provider Architecture and Subscription Passthrough Security
CodeWiki provides three distinct inference integration tracks: the API Key track, the OAuth subscription passthrough track, and the MCP tool track.
- CodeWiki Provider Backends
-
- API KeyPydanticAI
- OAuth SubCawBackend
- MCP Servercodewiki mcp
1. The API Key Track (PydanticAIBackend)
Implemented in pydantic_ai_backend.py, this track integrates via pydantic-ai with openai-compatible, anthropic, bedrock, azure-openai, google (both Gemini API and Vertex AI), and atlas.
This track provides the most robust engineering safeguards: it subclasses OpenAIChatModel in llm_services.py to handle non-standard proxy responses, automatically injects Anthropic-style prompt caching breakpoints, and maintains a denylist for unsupported models. Furthermore, only the API Key track supports --fallback-model, chaining backup models automatically via FallbackModel.
Credential management follows a zero-secrets config design (config_manager.py): API keys are written to the system keyring (such as macOS Keychain) by default. Only when a keyring service is unavailable (e.g., headless Linux containers or CI runners lacking X11/D-Bus) does it fall back to ~/.codewiki/credentials.json. Credentials can also be supplied directly via standard environment variables, leaving ~/.codewiki/config.json exclusively for non-sensitive settings.
Concurrency and retries are governed by request_limit (default: 100) and agent_retries (default: 3). Model pricing for input, output, and cache reads can be customized using:
codewiki config pricing set MODEL --input RATE --output RATE
2. The OAuth Subscription Passthrough Track (CawBackend) and Bypass Risks
Setting the provider to claude-code or codex switches execution to CawBackend (caw_backend.py), which uses a third-party wrapper layer—caw (coding-agent-wrapper)—to drive the locally authenticated official claude or codex CLIs via OAuth.
In this mode, --main-model operates in passthrough: any model identifier accepted by the underlying CLI (such as gpt-6.1-terra in the Codex CLI namespace) can be used directly. However, --fallback-model is explicitly ignored on the subscription track.
Before enabling the subscription track on private repositories, engineers must understand the four low-level workarounds embedded in caw_backend.py to allow CLI agents to complete long-running workflows without human intervention:
- Direct dependency on an unpinned personal Git repository: The
pyproject.tomldependencies hardcodecoding-agent-wrapper @ git+https://github.com/anhnh2002/caw@main(anhnh2002is lead author Anh Nguyen Hoang) without pinning a commit hash. - Disabled sandbox and bypassed approvals for Codex: When
codex execruns non-interactively in the background without elevated permissions (caw’sEXECmode), MCP tool calls that require approval are aborted outright. To prevent execution failures,caw_backend.pymaps execution flags to--dangerously-bypass-approvals-and-sandboxand monkey-patches tool timeouts to 24 hours (tool_timeout_sec=86400). - Subprocess monkey-patching to circumvent Claude policy downgrades: In enterprise-managed environments, organizational policies may downgrade requested bypass permissions to
acceptEdits(allowing file edits only), blocking CodeWiki’s custom MCP tools. To circumvent this, the runtime patchessubprocess.Popeninside the caw module in-memory, injecting--allowedTools mcp__<server>into every invocation to force tool approvals. - Hardcoded working directories: Because the two CLIs resolve relative paths differently, child process working directories (
cwd) are pinned explicitly—to the documentation output directory forcodexand to the target repository root forclaude.
CAUTION
Exercise caution with subscription passthrough on private repositories: The codex subscription track spawns subprocesses with --dangerously-bypass-approvals-and-sandbox, while its underlying wrapper pulls directly from an unpinned external Git branch. When documenting proprietary codebases, run inside an isolated container or use the API Key or MCP tracks instead.
NOTE
Further reading: A Beginner’s Guide to Container Runtimes (Part 1): Core Mechanics
3. The MCP Tool Track (codewiki mcp)
To run CodeWiki without configuring any LLM credentials inside the tool itself, start codewiki mcp (implemented in codewiki/mcp/) and delegate inference to external IDEs or hosts (Cursor, Claude Desktop, Claude Code, or CodeBuddy).
In this mode, CodeWiki operates strictly as a tool server, exposing five tool categories: analysis, code_reader, module_tree, doc_writer, and prompt_server. The repository also provides skills/codewiki-wiki-generator/SKILL.md for coding agents to mount directly.
NOTE
Further reading: Getting Started with Pi Coding Agent: A Minimal Core, Session Trees, and the 1.0 Update
Calibrating Local Config: Eliminating 10x Token Inflation and Clarifying max_depth
Inspecting certain local configuration files (~/.codewiki/config.json) or legacy benchmark reports frequently reveals inherited token settings like 327680, 363690, and 160000. Cross-referencing default values in config.py confirms that these figures stem from an extra zero accidentally appended, causing a 10x to 20x inflation:
Setting (config.json) | Common Inflated Value | v1 Historical Default | v2 Current Default (config.py) | Actual Controlled Behavior |
|---|---|---|---|---|
max_tokens | 327680 | 32,768 | 32,768 | Maximum output tokens per LLM invocation |
max_token_per_module | 363690 | 36,369 | 36,369 | Capacity threshold determining whether module clustering splits further |
max_token_per_leaf_module | 160000 | 16,000 | 8,000 | Maximum capacity for leaf modules (indivisible base modules) |
max_depth | Mistaken as clustering depth | 2 | 2 | Maximum delegation depth when authoring agents recursively spawn sub-agents |
While inflating these thresholds tenfold will not crash the program, it prevents the clustering phase from splitting modules, defeating the purpose of fine-grained architectural decomposition. Resetting ~/.codewiki/config.json to 32768 / 36369 / 8000 restores clustering behavior to its officially tuned baselines.
The distinct roles of these parameters reflect the division of labor across the parsing, clustering, and authoring stages:
- Phase 1: Static Parsing and Artifact Ingestion (
ast_parser.py,analyzers/): Across the 17 supported languages, 16 usetree-sitter, while Python alone uses the standard libraryastmodule, constructing directeddepends_onedges and filtering out standard library calls. v2.0 introduces artifact-aware analysis (analyzers/artifact.py), linking Dockerfiles, CI workflows, and configuration files into the dependency graph beforeleaf_selection.pyidentifies entry-point components. - Phase 2: LLM Semantic Clustering and Guardrails (
cluster_modules.py): Module boundaries are determined by the LLM rather than graph partitioning algorithms. The engine batches components by directory and prompts the model to cluster them. If a module exceedsmax_token_per_module(36,369 tokens), it is recursively divided until it falls below the threshold or the remaining volume is less than twicemin_token_per_module(1,000 tokens, guarding against tiny fragments). Inflatingmax_token_per_moduletriggers termination conditions prematurely. Guardrails include component uniqueness validation, a structured fallback that bins components by directory prefix and token budget if batch clustering fails, and a rule forcing the insertion of a"Build, Deployment and Configuration"fallback module if over 20% of build/CI components are unassigned. - Phase 3: Recursive Agent Authoring (
max_depth = 2): Authoring agents write documentation using file editors, component readers, and submodule generation tools.max_depthstrictly limits the delegation depth when spawning child agents during authoring; it has nothing to do with clustering depth in the previous phase. Additionally, inline module trees and source code embedded intoUSER_PROMPTare capped at 900,000 characters (prompt_template.py, designed to stay below the1,048,576-characterinput_too_largehard limit on Codex servers). When the budget is exceeded, inline content is truncated, requiring agents to fetch source files on demand via tool calls.
NOTE
Further reading: Context Engineering: Why Larger Windows Haven’t Made Agents More Reliable
CLI Generation in Practice: Localization, Custom Instructions, and Layouts
When executing generation tasks, frequently used CLI flags include:
- Generating localized documentation (
--language zh-TW): The built-in localization flag accepts language codes or names to generate output in Traditional Chinese (or other target languages), while generated filenames and module identifiers remain strictly in ASCII to prevent broken URL routes. - Injecting custom guidelines (
--instructions): Teams can pass project-specific instructions, such as"Target audience: DevOps engineers". These directives are wrapped in<CUSTOM_INSTRUCTIONS>tags and injected into the system prompts across all module runs and the top-level overview page (overview.md). - Configuring doc types and scope (
--doc-type,--focus):--doc-typesupports four modes:api,architecture,user-guide, anddeveloper. Pairing it with--focusconcentrates coverage on specific subsystems, while--github-pages --create-branchand--techdocsexport directly into ready-to-publish formats. - Selecting directory layouts (
hierarchicalvs.flat):doc_layout.pydefines two structural layouts: the defaulthierarchicalmode organizes files into nested directories following the module tree (e.g.,auth/session/store.md), whereasflatflattens all.mdfiles into the root directory (ideal for smaller LLMs prone to generating broken relative links; CodeWiki’s own 35-page documentation adoptsflat). - Zero-cost resume from checkpoints: Before generating each module, the engine checks whether the target file already exists and is reusable; if so, it skips generation. It also validates that files were successfully written to disk after execution, preventing agents from reporting success when nothing was actually written to disk.
Following a full build, the docs/ directory contains five standard artifacts: overview.md, individual module .md files, module_tree.json, metadata.json (tracking commit hashes and run metadata), and a temp/ scratch directory storing the serialized dependency graph and component indexes required for subsequent --update diffs.
Component-Level Incremental Updates: The Six-Step Pipeline and Tuning for 1.6% Cost
The bottleneck in initial full builds lies in the protracted LLM authoring loop. With v2.0’s --update flag enabled, updating documentation for a single commit on Svelte dropped to 3 minutes and $0.34—roughly 1.6% of a full rebuild.
Implemented in codewiki/src/be/updater/, this update engine moves beyond naive file-level git diff comparisons. Instead, it operates on a six-step pipeline treating components (classes, functions, build files) as units of change, and leaf modules as units of work.
A strict prerequisite for running --update is retaining module_tree.json and the temp/ cache directory (which stores previous component hashes and call graphs) in the output directory. Without them, the diff engine triggers a detector_failure and falls back immediately to a full rebuild:
- Step 1: Graph Diff (graph_diff.py)Hash & sig diff: comment-only edits = zero; Del + add with >= 95% sim (--tau-ren) = rename
- Step 2: Module Tree HealingRules: same file -> same dir -> neighbor majority; Routing agent fallback; > 33% growth reclusters
- Steps 3 & 4: Leaf Reports & Fallback EvaluationTrack edits + upstream (1 hop) + cited symbols; Fall back if > 50% active or > 30% tree change
- Steps 5 & 6: Topological Dispatch & Post-AuditIn-place patch, rewrite, or no-op on pages; Prune dead links; log audit to update_record.json
Update Rungs and CI Parameter Tuning
In production workflows, pipeline execution depth and fallback thresholds can be fine-tuned via CLI flags:
- Selecting update rungs (
--update-rung): Five rungs (0through3b) control pipeline execution depth:0falls back to 1.x behavior (rebuilding entire modules upon any file change);1runs Step 2 rule-based routing only;2adds the routing agent and Step 3 one-hop upstream propagation; default3enables full Step 5 in-place page patching; and3bexpands upstream dependency tracking (--k-hop) to two hops. - Tuning fallback and reclustering thresholds (
--tau-*): If default sensitivity proves too eager or sluggish during major refactorings, engineers can tune the rename similarity threshold--tau-ren(default:0.95), the neighbor routing threshold--tau-nb(0.5), the module split growth ratio--tau-grow(0.33), and the fallback triggers: active module ratio--tau-full(0.5) and structural change ratio--tau-tree(0.3).
TIP
Override the comparison baseline when using squash merges in CI: When teams merge PRs into trunk via squash merges or rebases, individual commit hashes previously recorded in metadata.json vanish from Git history, causing trunk CI to lose its diff baseline. Pass --compare-to HEAD~1 explicitly to supply a valid comparison target.
- Automated audit trails (
update_record.json): Every update run terminates in one of four distinct states:no_change(zero LLM calls, zero cost),incremental,full_fallback(recording triggering ratios), ordetector_failure(the stored graph fails to load). All decisions and invocation costs are logged for retrospective auditing.
Practical Engineering Boundaries
Benchmark results from CodeWikiBench in the ACL 2026 Findings paper (arXiv:2510.24428), combined with the main branch implementation, clearly delineate the strengths and limitations of this “static extraction, LLM clustering” architecture.
In high-level scripting languages, CodeWiki shines: it achieves an overall score of 68.79%, outpacing the commercial version of DeepWiki (64.06%), deepwiki-open (50.05%), and OpenDeepWiki (47.13%). On Python, JavaScript, and TypeScript repositories (such as puppeteer and OpenHands), it outperforms commercial DeepWiki by 10.47 percentage points.
For Go and Dart/Flutter added in main, the analyzers incorporate handwritten, framework-level attribution heuristics—such as mapping Go methods to receiver types, binding Flutter Riverpod providers and routes to corresponding screens, and automatically ignoring generated *.g.dart files.
Conversely, low-level C/C++ systems projects remain an architectural bottleneck: on wazuh (1.4 million lines of C) and electron (184,000 lines of C++), CodeWiki trails DeepWiki, 53.24% versus 56.39%. The authors attribute this deficit to pointer arithmetic, manual memory management, and template metaprogramming; static AST edges and semantic clustering alone struggle to accurately reconstruct the architecture of low-level systems.