Overview

Google recently launched Code Wiki (Nov 2025, public preview) — a Gemini-powered tool that takes any public GitHub repository and generates comprehensive, interactive documentation including architecture diagrams, class diagrams, sequence diagrams, module-by-module walkthroughs, and a context-aware chatbot. It auto-updates when PRs merge, and every section hyperlinks directly to source code.

This proposes a native Code Wiki skill for Hermes Agent that replicates this core value proposition — transforming any codebase (local or remote, public or private) into a comprehensive documentation package using the agent's existing tools and the user's configured LLM. No external services, no extra dependencies — just structured instructions that produce high-quality docs and Mermaid diagrams.

The capability fills a genuine gap. Hermes can already read and understand code on-demand, but lacks a systematic workflow for generating comprehensive, organized documentation from a full codebase. This is distinct from the Theorist skill (#381), which maintains a strategic narrative about why a system works a certain way — Code Wiki generates reference documentation about what the system is and how it works.

Research Findings

How Google CodeWiki Works

Google's Code Wiki (blog post) is built on three pillars:

1. Automated & Always Up-to-Date — Scans the full codebase and regenerates documentation after every change, so docs evolve alongside code.
2. Intelligent & Context-Aware — Integrated Gemini-powered chat uses the generated wiki as its knowledge base, not just the raw code.
3. Integrated & Actionable — Every section and chat response hyperlinks directly to relevant code files, classes, and function definitions.

Key features:

• Interactive navigation from high-level concepts to specific functions
• Auto-generated architecture, class, and sequence diagrams
• Gemini-powered Q&A chatbot grounded in the wiki content
• Auto-updates on PR merge
• Currently public repos only; private repo support coming via Gemini CLI extension (waitlist)

Limitations:

• Hosted service only — not self-hostable, no API, no CLI
• Public repos only (private support in waitlist/future)
• Dependent on Google's infrastructure and Gemini
• No customization of output format or structure

Open Source Alternatives Researched

DeepWiki-Open — The most mature open-source alternative. Self-hostable via Docker, supports multiple LLM providers (Gemini, OpenAI, OpenRouter, Ollama), RAG pipeline for code Q&A, Mermaid diagram generation. Requires Docker + Redis + Python + Node.js. Development is shifting to a new repo (AsyncReview). No clear license statement on the main README.

GitDiagram (MIT, 15.2K stars) — Focused specifically on architecture diagram generation. Takes a repo's file tree + README, uses a 3-step LLM pipeline to generate interactive Mermaid diagrams with clickable nodes linking to source files. Lightweight compared to full wiki generators. Uses OpenAI GPT. This is the inspiration for several clones.

codewiki (Apache-2.0, 11 stars) — Small open-source clone combining GitDiagram + DeepWiki-Open. TypeScript/Python, Docker + Redis. Generates diagrams + wiki + chat. Too small/immature for production use.

Key Design Decisions Across Implementations

1. Mermaid.js is the standard — All implementations use Mermaid syntax for diagrams. It renders natively on GitHub, GitLab, and most documentation platforms. No image generation needed.
2. Repo structure is the primary input — File tree + README provide enough signal for architecture diagrams. Deeper analysis (reading actual source files) is needed for class/sequence diagrams and module docs.
3. RAG for chat quality — DeepWiki-Open and CodeWiki both embed code chunks for retrieval, making the chatbot more accurate than raw LLM prompting. For Hermes, the agent's existing file reading tools serve the same purpose.
4. Incremental updates beat full regeneration — For large repos, only regenerating docs for changed modules is critical for performance.

Current State in Hermes Agent

What we have:

• Codebase inspection skill: LOC counting, language breakdown via pygount — basic metrics only, no documentation generation
• Excalidraw skill: Creates hand-drawn style diagrams in Excalidraw JSON — different format and purpose (manual creation, not auto-generation)
• Theorist skill (Feature: Theorist Skill — Per-Repo Operating Theory Documents (inspired by blader/theorist) #381): Maintains a living THEORY.MD about strategic understanding — complementary but fundamentally different (narrative "why" vs. reference "what/how")
• The agent itself: Can already read code files, answer questions, and generate Mermaid diagrams when asked — but no structured workflow to produce comprehensive docs
• search_files, read_file, write_file: All the tools needed to scan, analyze, and output documentation already exist

Gap: No systematic skill for generating comprehensive, structured documentation from a codebase. The agent can do it ad-hoc if prompted, but without a structured approach it produces inconsistent, incomplete results and doesn't know the optimal workflow for large repos.

Related issues:

• Feature: Theorist Skill — Per-Repo Operating Theory Documents (inspired by blader/theorist) #381 (Theorist Skill) — Complementary, not overlapping. Theorist = strategic understanding narrative; Code Wiki = reference documentation
• Feature: Skill Lifecycle Quality — Better Descriptions, Proactive Improvement Loop, and Writing Principles (inspired by Anthropic skill-creator) #429 (Skill Lifecycle Quality) — Not related

Implementation Plan

Skill vs. Tool Classification

This should be a bundled skill because:

• The capability can be expressed entirely as instructions + existing tools (search_files for repo scanning, read_file for source analysis, write_file for doc output, terminal for git operations)
• No custom Python integration needed — the LLM's own analytical capabilities drive the documentation generation
• No API key management beyond what's already configured
• No binary data, streaming, or real-time events
• Broadly useful — generating documentation from codebases is valuable to virtually every developer using Hermes

Per CONTRIBUTING.md criteria: "Make it a Skill when the capability can be expressed as instructions + shell commands + existing tools."

What We'd Need

1. A new skill at skills/software-development/code-wiki/SKILL.md
2. A template for the output directory structure
3. Mermaid diagram generation instructions (architecture, class, sequence)
4. Module analysis and documentation generation workflow
5. Support for both local repos and GitHub URLs

Output Location

Default: external to the repo — ~/.hermes/wikis/<repo-name>/. This matches Google's approach: CodeWiki hosts docs on codewiki.google, never modifying the repository itself. Generated docs are for the user's understanding, not committed to the codebase by default.

Optional: in-repo — Users can explicitly request output to docs/wiki/ (or any path) inside the repo if they want to commit and share the generated docs. This makes Mermaid diagrams render on GitHub, but adds auto-generated files to the working tree.

Output Structure

~/.hermes/wikis/<repo-name>/
├── README.md              # Project overview, purpose, key concepts
├── architecture.md        # Architecture overview with Mermaid diagrams
├── modules/
│   ├── module-a.md        # Per-module deep dive
│   ├── module-b.md        # Each with: purpose, key files, data flow, API
│   └── ...
├── diagrams/
│   ├── architecture.md    # System architecture (Mermaid flowchart)
│   ├── class-diagram.md   # Key class relationships (Mermaid classDiagram)
│   └── sequences.md       # Core workflows (Mermaid sequenceDiagram)
├── api.md                 # API reference (if applicable)
└── getting-started.md     # Setup, configuration, first steps

All Mermaid diagrams render natively on GitHub if placed in-repo — and in any markdown viewer otherwise.

Phased Rollout

Phase 1: Core Documentation Generation

• Skill that scans repo structure (search_files, terminal for tree/git log)
• Generates architecture overview with Mermaid architecture diagram
• Per-module documentation for top-level directories
• Getting started guide from README + setup files
• Works on local repos (cwd)

Phase 2: Advanced Diagrams & Remote Repos

• Class diagrams from source analysis
• Sequence diagrams for core workflows
• API documentation extraction
• Support for GitHub URLs (clone → generate → output)
• Cross-referencing with hyperlinks back to source files (GitHub-compatible links)

Phase 3: Incremental Updates & Integration

• Detect changed files (via git diff) and only regenerate affected sections
• Integration with Theorist (Feature: Theorist Skill — Per-Repo Operating Theory Documents (inspired by blader/theorist) #381) — Code Wiki for "what/how", Theorist for "why"
• Support for delegate_task to parallelize module analysis on large repos
• Optional: generate a docs/wiki/.codewiki-state.json tracking what was generated and when
• Consider auto-trigger on significant codebase changes during development sessions

Pros & Cons

Pros

• Zero dependencies — Uses only existing Hermes tools (read_file, search_files, write_file, terminal). No Docker, Redis, or external services.
• Works on everything — Local repos, private repos, any language. Not limited to public GitHub repos like Google's CodeWiki.
• GitHub-native output — Mermaid diagrams render directly on GitHub. Markdown docs work everywhere.
• Model-agnostic — Uses whatever LLM the user has configured. Works with GPT, Claude, Gemini, open-source models.
• Complements existing features — Fills the gap between basic codebase-inspection (metrics) and Theorist (strategic narrative).
• Broadly useful — Every developer benefits from better documentation. Strong candidate for bundled skill.
• Customizable — Users can modify the skill to adjust output format, depth, and structure.

Cons / Risks

• Token-intensive for large repos — Generating comprehensive docs for a large codebase requires reading many files. Mitigated by Phase 3's incremental updates and delegate_task parallelization.
• Quality depends on LLM — Documentation quality varies by model capability. Stronger models (GPT-4+, Claude 3.5+) will produce better results than small models.
• Not truly "interactive" — Google's CodeWiki has a web UI with clickable diagrams. Our output is static markdown with Mermaid. The diagrams render but aren't clickable-to-navigate like a web app.
• No auto-update — Unlike Google's service which regenerates on PR merge, our docs are generated on-demand. Phase 3 adds incremental support but not CI/CD-triggered updates.
• Large output — For big repos, the generated docs could be substantial. Need clear guidance on scope control (e.g., max depth, module selection).
• Mermaid limitations — Very complex architectures may exceed Mermaid's rendering capabilities or produce unreadable diagrams. May need to split into sub-diagrams.

Open Questions

• Resolved: Output defaults to ~/.hermes/wikis/<repo-name>/ (external, like Google's approach). Users can opt into in-repo output (e.g., docs/wiki/) when they want to commit the generated docs.
• How deep should module analysis go? Top-level directories only, or recursive? Should users control this?
• Should we support a "quick mode" (structure + overview only, ~2 min) vs. "deep mode" (full module analysis, ~10-15 min)?
• Should the skill integrate with GitHub Pages or other hosting for a browsable wiki experience?
• For Phase 3 incremental updates: should we track state in a JSON file or infer changes from git diff?
• Should the skill auto-detect the project type (web app, library, CLI tool, ML project) and adjust documentation templates accordingly?

References

• Google Code Wiki: https://codewiki.google/
• Google Developer Blog announcement: https://developers.googleblog.com/introducing-code-wiki-accelerating-your-code-understanding/
• DeepWiki-Open (open source alternative): https://github.com/AsyncFuncAI/deepwiki-open
• GitDiagram (MIT, 15.2K stars, diagram-focused): https://github.com/ahmedkhaleel2004/gitdiagram
• codewiki open-source clone (Apache-2.0): https://github.com/quangdungluong/codewiki
• Hermes Theorist Skill (complementary): Feature: Theorist Skill — Per-Repo Operating Theory Documents (inspired by blader/theorist) #381
• Hermes Codebase Inspection Skill (basic metrics): skills/github/codebase-inspection/
• Mermaid.js documentation: https://mermaid.js.org/