DEV Community

Cover image for wikigen: Auto-generate specification docs from your codebase
Owada Tomohiro
Owada Tomohiro

Posted on

wikigen: Auto-generate specification docs from your codebase

#ai #automation #cli #documentation

The problem

Documentation gets written once and goes stale. Engineers don't update it. New team members keep asking "where is this API called from?" and "what's this table for?"

I wanted documentation that stays in sync with code — generated directly from the source, not written by hand.

Existing solutions

DeepWiki by Devin generates wiki-style documentation from repositories. The approach — using AI to read code and produce docs — was exactly what I was looking for.

However, for my use case (batch generation across private repos, CI/CD integration), I needed something I could run from the command line without a UI.

The open-source DeepWiki-Open lets you self-host, but requires Docker + Ollama (for embedding) + an LLM backend. That's a lot of infrastructure for generating docs.

The realization

DeepWiki-Open's pipeline is:

clone → embedding → RAG search → LLM generates docs
Enter fullscreen mode Exit fullscreen mode

But Claude Code can already explore codebases. Give it --add-dir and it uses Read, Grep, Glob, and Bash to find and read whatever files it needs. No embedding, no vector DB, no RAG.

clone → claude -p --add-dir ./repo → reads code directly → writes docs
Enter fullscreen mode Exit fullscreen mode

What I built

wikigen is a single-binary CLI that generates GitHub Wiki from source code.

./wikigen owner/repo
Enter fullscreen mode Exit fullscreen mode

That's it. It clones the repo, lets Claude Code explore the code, and outputs GitHub Wiki-compatible Markdown files.

What gets generated

The document structure follows categories from ISO/IEC 12207 (software lifecycle documentation), filtered to what's actually derivable from code:

Factual (directly from code):

  • System overview, architecture, API specifications
  • Data models (from migrations, ORM definitions)
  • Config, environment variables, build/deploy procedures
  • Test structure, auth flows, error handling

High-confidence inference (from code patterns):

  • Processing flows (from function call chains)
  • Security design (from middleware, validation)

Not generated:

  • Business requirements, risk assessments, SLAs — anything that would be speculation

The prompt explicitly says: "If there's no code evidence, don't write it. Don't even mention that you couldn't find it."

Multi-repo projects 

myproject:owner/frontend
myproject:owner/backend
myproject:owner/shared
Enter fullscreen mode Exit fullscreen mode

Multiple repos get merged into one wiki with cross-repository documentation — architecture pages that show how services interact.

Parallel generation 

./wikigen -f repos.txt -p 2 -pp 5
Enter fullscreen mode Exit fullscreen mode

-p 2 runs 2 repos in parallel, -pp 5 generates 5 pages per repo simultaneously.

GitHub Actions integration

Wiki auto-updates when you push to main:

- name: Generate wiki
  env:
    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
  run: wikigen -lang en -pp 3 -local . my-project
Enter fullscreen mode Exit fullscreen mode

No clone needed in CI — the checkout action already has the code.

Error handling

  • Each page auto-retries up to 3 times
  • ./wikigen -retry regenerates only failed pages
  • Pages save immediately — partial results survive interruptions

Output format

GitHub Wiki-compatible. Push directly to {repo}.wiki.git:

wiki-output/project/
  Home.md
  _Sidebar.md
  System-Architecture.md
  API-Specification.md
  Data-Model.md
  ...
Enter fullscreen mode Exit fullscreen mode

Cross-page links use [Page Title](Page-Filename) format. _Sidebar.md provides navigation.

See a real example: github.com/tomohiro-owada/wikigen/wiki

What went wrong along the way

claude -p output had commentary mixed in. The generated docs would start with "Sure, I'll create the wiki page for you." Fixed by telling Claude to use the Write tool to save files directly, and having Go read the files instead of stdout.

The dialect incident. My Claude Code session was configured to respond in Kyoto dialect. The generated documentation came out saying things like "This API accepts POST requests, ya know." Added "formal technical language only, no dialects" to the prompt.

Prerequisites

  • Go 1.22+
  • git (SSH or PAT)
  • Claude Code CLI, authenticated 
git clone https://github.com/tomohiro-owada/wikigen.git
cd wikigen
go build -o wikigen .
./wikigen owner/repo
Enter fullscreen mode Exit fullscreen mode

Links

Inspired by DeepWiki-Open.

Top comments (0)