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:

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.

  1. CodeWiki Provider Backends
    1. API KeyPydanticAI
    1. OAuth SubCawBackend
    1. 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:

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.

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.


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 Valuev1 Historical Defaultv2 Current Default (config.py)Actual Controlled Behavior
max_tokens32768032,76832,768Maximum output tokens per LLM invocation
max_token_per_module36369036,36936,369Capacity threshold determining whether module clustering splits further
max_token_per_leaf_module16000016,0008,000Maximum capacity for leaf modules (indivisible base modules)
max_depthMistaken as clustering depth22Maximum 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:

  1. Phase 1: Static Parsing and Artifact Ingestion (ast_parser.py, analyzers/): Across the 17 supported languages, 16 use tree-sitter, while Python alone uses the standard library ast module, constructing directed depends_on edges 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 before leaf_selection.py identifies entry-point components.
  2. 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 exceeds max_token_per_module (36,369 tokens), it is recursively divided until it falls below the threshold or the remaining volume is less than twice min_token_per_module (1,000 tokens, guarding against tiny fragments). Inflating max_token_per_module triggers 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.
  3. Phase 3: Recursive Agent Authoring (max_depth = 2): Authoring agents write documentation using file editors, component readers, and submodule generation tools. max_depth strictly 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 into USER_PROMPT are capped at 900,000 characters (prompt_template.py, designed to stay below the 1,048,576-character input_too_large hard limit on Codex servers). When the budget is exceeded, inline content is truncated, requiring agents to fetch source files on demand via tool calls.

CLI Generation in Practice: Localization, Custom Instructions, and Layouts

When executing generation tasks, frequently used CLI flags include:

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:

  1. Step 1: Graph Diff (graph_diff.py)Hash & sig diff: comment-only edits = zero; Del + add with >= 95% sim (--tau-ren) = rename
  2. Step 2: Module Tree HealingRules: same file -> same dir -> neighbor majority; Routing agent fallback; > 33% growth reclusters
  3. Steps 3 & 4: Leaf Reports & Fallback EvaluationTrack edits + upstream (1 hop) + cited symbols; Fall back if > 50% active or > 30% tree change
  4. 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:

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.


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.