Claude Code Integration

Wikigen delegates all code analysis and documentation generation to Claude Code via the claude CLI in project mode. Rather than implementing its own code parser or analysis engine, wikigen orchestrates Claude Code invocations with repository directories passed through the --add-dir flag, enabling Claude to use its native tools (Read, Grep, Glob, Bash) to examine source code before generating wiki-compatible Markdown. This page explains how wikigen invokes Claude Code, the system prompts and structured prompts used to guide generation, the patterns of tool interaction, and the error handling mechanisms that ensure reliable wiki generation.

Overview of Claude Code Integration

Wikigen's architecture is fundamentally built around delegating all code analysis, reasoning, and documentation writing to Claude Code. The main orchestration engine (written in Go) performs no code parsing, pattern analysis, or architectural decision-making. Instead, it:

Clones or locates repositories and resolves them to absolute local directory paths
Invokes Claude Code processes with repository directories granted via --add-dir
Provides structured prompts that guide Claude's analysis and generation
Captures Claude's output and parses XML structures or writes Markdown files
Handles retry logic, error logging, and partial result preservation for reliability

This delegation model ensures that Claude Code's full suite of tools and reasoning capabilities are leveraged for accurate, evidence-based documentation.

Sources: main.go:1-17, main.go:137-164

Claude Code Invocation

The claudeCall Function

The primary mechanism for invoking Claude Code is the claudeCall() function, which constructs and executes a Claude process with appropriate command-line arguments, system prompts, and input text.

func claudeCall(claudePath, model string, repoDirs []string, systemPrompt, prompt, workDir string) (string, error) {
	args := []string{"-p", "--output-format", "text", "--dangerously-skip-permissions"}
	if model != "" {
		args = append(args, "--model", model)
	}
	for _, dir := range repoDirs {
		args = append(args, "--add-dir", dir)
	}
	if systemPrompt != "" {
		args = append(args, "--system-prompt", systemPrompt)
	}

	cmd := exec.Command(claudePath, args...)
	cmd.Stdin = strings.NewReader(prompt)
	if workDir != "" {
		cmd.Dir = workDir
	}

	var stdout, stderr bytes.Buffer
	cmd.Stdout = &stdout
	cmd.Stderr = &stderr

	if err := cmd.Run(); err != nil {
		return "", fmt.Errorf("claude: %v\nstderr: %s", err, stderr.String())
	}

	return strings.TrimSpace(stdout.String()), nil
}

Sources: main.go:137-164

Command-Line Arguments

Each Claude Code invocation is constructed with a specific set of command-line arguments that control behavior and permissions:

Argument	Purpose	Details
`-p`	Project mode	Enables tool access (Read, Grep, Glob, Bash) for specified directories
`--output-format text`	Output format	Plain text output; prevents markdown code fence wrapping
`--dangerously-skip-permissions`	Permission bypass	Allows automated invocation without user interaction prompts
`--add-dir <dir>`	Repository access	Grants file system access to a directory; multiple directories can be added via multiple arguments
`--model <model>`	Model selection	Specifies Claude model (haiku, sonnet, opus); optional, overrides environment variable
`--system-prompt <text>`	System instructions	Passed only during structure determination phase; controls XML formatting

Sources: main.go:138-147

Repository Directory Resolution

Repository directories are passed to Claude Code via --add-dir for file system access. Wikigen resolves repositories to local directories through three mechanisms:

Remote GitHub repositories — cloned via git clone --depth=1 with shallow clone for efficiency, then passed as absolute paths
Local directories specified in repos.txt — validated to ensure they contain code, then passed as absolute paths
Local directory via -local flag — a single local directory specified directly on the command line

All directories are converted to absolute paths before being passed to Claude Code, ensuring consistent tool behavior regardless of wikigen's working directory or the user's current shell directory.

Sources: main.go:168-192, main.go:504-546

System Prompts and Prompt Engineering

Wikigen uses distinct prompts depending on the phase of generation: one specialized system prompt for structure determination and one detailed user prompt for individual page generation.

XML System Prompt (Structure Phase)

During structure determination, Claude Code must produce well-formed XML output without markdown code fence wrapping. The system prompt enforces this critical constraint:

CRITICAL INSTRUCTIONS FOR XML RESPONSES:
When the user requests XML output (e.g., wiki_structure, or any XML format):
1. Return ONLY the raw XML - no markdown code fences, no backticks, no explanation
2. Do NOT wrap XML in triple backticks or markdown code blocks
3. Do NOT add any text before or after the XML
4. Start directly with the opening XML tag and end with the closing XML tag
5. Ensure the XML is well-formed and valid

Sources: main.go:196-202

This system prompt is applied only during Phase 1 (structure determination). It prevents Claude from adding markdown code blocks around the XML output, which would cause downstream XML parsing to fail. The --system-prompt flag is not used during page generation; page generation relies on the detailed user prompt alone.

Structure Determination Prompt

The structurePrompt() function generates a comprehensive prompt that instructs Claude Code to analyze the repository codebase and design a wiki structure. This prompt is approximately 190 lines and contains multiple sections:

Key instructions in the structure prompt:

Tool usage directive — explicitly instructs Claude Code to "USE the Read, Grep, Glob, and Bash tools to thoroughly examine the codebase before designing the structure"
Documentation categories — provides 13 predefined categories spanning core documentation (System Overview, Architecture, API Specification, Data Model, etc.) and inferred documentation (Processing Flows, Security Design, Performance Considerations), with instruction to create pages "AS APPLICABLE"
Quality rules — mandates that "Each page MUST map to actual files in the repositories" and "If a category has no corresponding code, do NOT create a page — simply omit it"
Multi-repo guidelines — provides specific instructions for grouped projects: "When multiple repositories form one project, create CROSS-REPOSITORY documentation" and "Show how repositories interact with each other"
Output format specification — specifies exact XML schema with <wiki_structure>, <pages>, <page> elements, each containing <title>, <filename>, <description>, <importance>, <relevant_files>, and <related_pages> sub-elements

Sources: main.go:204-294

The prompt emphasizes factual, code-based documentation: "Your task is to determine what documentation pages are needed based on WHAT ACTUALLY EXISTS in the codebase." This ensures that speculative or templated pages are avoided.

Page Generation Prompt

The pagePrompt() function generates a context-rich prompt for each individual wiki page. This prompt includes:

Full page context — the page title and description to be written
Project and repository information — all repositories being documented in the wiki
Tool availability reminder — "USE the Read, Grep, Glob, and Bash tools to read actual source files before writing"
Quality directives — "Do NOT guess or speculate — read the code first, then document what you find"
Cross-page linking context — a list of all other pages with their titles, descriptions, and filenames for cross-reference creation
Content requirements — detailed sections covering what should be in the page (introduction, detailed sections with diagrams, tables, code snippets, source citations, cross-links)
Mermaid diagram guidance — explicit instructions to use flowchart TD, sequenceDiagram, classDiagram, and erDiagram, with constraints like "NEVER use LR" and "Keep node labels to 3-4 words max"
Output format instructions — instructions to use the Write tool to save the markdown file with specific heading structure and no console output

Sources: main.go:296-383

Each page generation invocation is completely independent; Claude Code is not provided a system prompt for page generation, only the detailed user prompt containing all necessary context.

Tool Interaction Patterns

Claude Code accesses repository code and writes output through four primary tools: Read, Grep, Glob, and Bash. The prompts guide Claude to use these tools to examine actual code before generating documentation.

Read Tool

The Read tool is used to examine individual file contents. The page prompt explicitly instructs Claude to "read actual source files before writing." In practice, Claude uses Read to:

Examine function implementations and signatures for API documentation
Read data structure definitions (structs, classes, types) for data model pages
Review comments and docstrings for implementation details
Analyze configuration files and environment variable usage
Study imports and dependencies for integration documentation

The Read tool returns file content with line numbers, enabling precise source citations in generated wiki pages. This is critical for production documentation where readers need to verify claims against the source code.

Grep Tool

The Grep tool performs regex-based pattern searches across files. Claude uses Grep to:

Search for specific function names or definitions
Find usages of key components or APIs
Locate configuration patterns and environment variable assignments
Search for API endpoint definitions, route handlers, and middleware
Identify error handling patterns and exception types

Grep allows sophisticated searches using regular expressions, enabling Claude to discover code patterns that are scattered across multiple files.

Glob Tool

The Glob tool performs file discovery by pattern matching against file paths. Claude uses Glob to:

List all files in a directory structure to understand project organization
Find files by extension (e.g., **/*.go, **/*.test.ts) for language-specific discovery
Discover configuration files (Dockerfile, docker-compose.yml, package.json, go.mod, etc.)
Identify test files and their organization (test/integration, tests, _test.go, etc.)
Map overall project structure and identify subdirectories

Glob outputs are sorted by modification time, helping Claude identify recently changed or active components.

Bash Tool

The Bash tool executes shell commands for metadata extraction and analysis. Claude uses Bash to:

Run git log to examine commit history and understand recent changes
Execute find commands for complex file discovery patterns
Inspect tool version information and dependency details
Check directory structures and file permissions

Bash is used sparingly to supplement Glob and Grep, primarily for git history examination.

Sources: main.go:215, main.go:313-314

Two-Phase Generation Flow

The integration of Claude Code into wikigen follows a two-phase architecture that separates structure determination from content generation. This separation enables efficient processing and parallel page generation.

Phase 1: Structure Determination

Structure determination is performed once per project group. The flow is:

1. Prepare repository directories via --add-dir for all repos in the group
2. Call claudeCall() with:
   - xmlSystemPrompt (XML formatting instructions)
   - structurePrompt() (analysis and documentation categories)
   - All repository directories passed to Claude Code
3. Claude Code:
   - Uses Read tool to examine key files (README, main entry points, etc.)
   - Uses Grep to search for patterns (API routes, config files, etc.)
   - Uses Glob to discover files (language-specific patterns, config files)
   - Analyzes code structure and determines required pages
   - Returns XML structure describing planned pages
4. Clean XML response (remove markdown code fences if present via cleanXMLResponse())
5. Parse XML using parsePages() function to extract page metadata
6. Extract page titles, filenames, descriptions from XML
7. Generate and write Home.md (landing page) and _Sidebar.md (navigation)

Sources: main.go:555-578, main.go:669-696

The cleanXMLResponse() function handles edge cases where Claude Code returns XML wrapped in markdown code fences, removing those wrappers before parsing:

Sources: main.go:401-418

Phase 2: Page Generation

After structure is determined, individual pages are generated in parallel using a semaphore pattern for concurrency control. For each page:

1. Call claudeCall() with:
   - No system prompt (only Phase 1 uses xmlSystemPrompt)
   - pagePrompt() containing:
     * Page title and description to be written
     * List of all other pages for cross-linking context
     * Full access to all repository directories
   - All repository directories (same as Phase 1)
   - Working directory set to wiki output directory
2. Claude Code:
   - Uses Read to examine actual source files for content
   - Uses Grep to find specific code examples and patterns
   - Uses Glob to discover file structures and organization
   - Generates comprehensive wiki page markdown
   - Uses Write tool to write the .md file directly to output directory
3. Wikigen detects file creation and validates success:
   - Checks if file was written and exceeds 100 bytes minimum
   - On success, marks page as complete and moves to next page
   - On failure, retries up to 3 attempts total
   - If all retries fail, writes error placeholder page and logs to _errors.log

Sources: main.go:599-646

The working directory (cmd.Dir) is set to the output wiki directory, allowing Claude Code to write files relative to that location without requiring absolute paths in the prompt.

Mermaid Diagram: Two-Phase Generation Flow

flowchart TD
    A["Repository<br/>Directories<br/>(via --add-dir)"]

    B["Phase 1:<br/>Structure<br/>Determination"]
    C["xmlSystemPrompt<br/>+<br/>structurePrompt"]
    D["Claude Code<br/>Process"]
    E["Read, Grep<br/>Glob, Bash"]
    F["XML Output:<br/>Wiki Structure"]
    G["Parse XML<br/>Extract Pages"]
    H["Generate<br/>Home.md &<br/>_Sidebar.md"]

    I["Phase 2:<br/>Page<br/>Generation<br/>Loop"]
    J["pagePrompt<br/>for Each Page"]
    K["Claude Code<br/>Process"]
    L["Read, Grep<br/>Glob, Bash<br/>Write"]
    M["Individual<br/>.md Files"]
    N["Error Handler:<br/>Retry up to 3x"]
    O["Error Page<br/>+ _errors.log"]

    A -->|once per<br/>project| B
    B --> C
    C --> D
    D --> E
    E -->|returns| F
    F --> G
    G --> H

    H -->|per-page<br/>in parallel| I
    A --> J
    J --> K
    K --> L
    L -->|Claude<br/>writes| M
    L -->|on failure| N
    N -->|success| M
    N -->|all retries<br/>fail| O

Invocation Sequence Diagram

sequenceDiagram
    participant Wikigen as Wikigen<br/>Orchestrator
    participant Claude as Claude Code<br/>Process
    participant Tools as Tools:<br/>Read/Grep/Glob
    participant Repo as Repository<br/>Directory
    participant Output as Output<br/>Directory

    Note over Wikigen: Phase 1: Structure
    Wikigen->>Claude: exec.Command("claude -p<br/>--add-dir <repo>")
    Wikigen->>Claude: stdin: structurePrompt
    Claude->>Tools: Glob: discover files
    Claude->>Tools: Read: examine key files
    Claude->>Tools: Grep: search patterns
    Claude->>Claude: Analyze codebase
    Claude->>Wikigen: stdout: XML structure

    Note over Wikigen: Phase 2: Pages (parallel)
    loop for each page
        Wikigen->>Claude: exec.Command("claude -p<br/>--add-dir <repo>")
        Wikigen->>Claude: stdin: pagePrompt
        Claude->>Tools: Read: source files
        Claude->>Tools: Grep: find examples
        Claude->>Tools: Glob: discover structure
        Claude->>Output: Write: Page.md
        Claude->>Wikigen: stdout: (empty or status)
    end
    Wikigen->>Wikigen: Validate file creation

Error Handling and Output Control

Output Format Control

Wikigen controls Claude Code's output format using the --output-format text flag. This produces plain text responses without markdown code fence wrapping, simplifying downstream processing and reducing the likelihood of parsing errors.

During Phase 1 (structure determination), the XML system prompt provides additional guidance to prevent Claude from adding markdown code fences around the XML output. This dual approach ensures robust XML parsing.

Sources: main.go:138

File Detection and Retry

Wikigen detects successful page generation by checking for file creation and minimum file size:

written, readErr := os.ReadFile(filename)
if readErr == nil && len(written) > 100 {
	page.Content = string(written)
	success = true
	break
}

If Claude Code does not write a file, or if the file is too small (< 100 bytes), the generation is considered failed and retried (up to 3 attempts total). The 100-byte minimum ensures that placeholder or stub responses are not accepted as valid wiki pages.

Sources: main.go:629-635

Error Logging

Failed page generations are logged to _errors.log in the output directory with ISO 8601 timestamps:

func appendError(dir, msg string) {
	errFile := filepath.Join(dir, "_errors.log")
	f, err := os.OpenFile(errFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
	if err != nil {
		return
	}
	defer f.Close()
	fmt.Fprintf(f, "[%s] %s\n", time.Now().Format(time.RFC3339), msg)
}

Each error log entry includes a timestamp and descriptive message indicating which page failed, how many attempts were made, and the attempt number. This enables post-mortem analysis and debugging of generation failures.

Sources: main.go:483-493

Parallel Invocation and Concurrency

While individual Claude Code invocations are sequential (one claudeCall() at a time), page generation is parallelized using Go goroutines with a channel-based semaphore pattern:

var pageSem = make(chan struct{}, pageParallel)
var pageWg sync.WaitGroup

for i := range allPages {
	pageWg.Add(1)
	pageSem <- struct{}{}  // acquire semaphore
	go func(idx int) {
		defer pageWg.Done()
		defer func() { <-pageSem }()  // release semaphore

		_, err := claudeCall(claudePath, model, repoDirs, "", pagePrompt(*page, allPages, projectName, repos, language), wikiDir)
		// ... error handling, file validation, retry logic
	}(i)
}
pageWg.Wait()

The semaphore limits concurrent Claude Code invocations to pageParallel (default 5), configured via the -pp flag. Multiple Claude processes run concurrently, each analyzing the same repositories via separate --add-dir arguments. This enables efficient parallel page generation while maintaining system stability.

Sources: main.go:595-646

Model Selection and Configuration

The Claude model can be specified via CLI flag (-model) or environment variable (CLAUDE_MODEL). The model name is passed to Claude Code via the --model argument:

if model != "" {
	args = append(args, "--model", model)
}

This allows users to choose between different Claude models (haiku, sonnet, opus) depending on cost/quality tradeoffs. Haiku is fast and cost-effective for many documentation tasks, while Sonnet and Opus provide higher quality for complex codebases.

Sources: main.go:139-141

Working Directory and Relative Paths

The workDir parameter in claudeCall() sets the working directory for the Claude Code process via cmd.Dir. This is set to the wiki output directory during page generation:

if workDir != "" {
	cmd.Dir = workDir
}

This ensures that when Claude Code uses the Write tool to write .md files, they are created relative to the output directory without requiring absolute paths in the prompt. Claude can simply use filename.md and the file will be written to the correct output location.

Sources: main.go:151-152, main.go:623

Requirements and Dependencies

Wikigen requires the claude CLI to be installed and authenticated. The Claude CLI must be in the system PATH or specified via the -claude flag:

# Verify claude CLI is available and authenticated
$ claude -p "hello"
Hello! I'm Claude...

# Or verify from wikigen
$ wikigen -help

The CLI is invoked as a subprocess via exec.Command(). Authentication is handled through the Claude CLI's own authentication mechanism (OAuth token or API key).

Sources: main.go:948, main.go:971-972

Summary: Tool Interaction Pattern

The interaction between wikigen and Claude Code follows this consistent pattern:

Wikigen orchestrates — clones repos, constructs prompts, manages concurrency, invokes Claude processes
Claude Code analyzes — uses Read, Grep, Glob, Bash tools to thoroughly examine source code
Claude Code generates — produces XML (Phase 1) or Markdown (Phase 2) based on analysis
Claude Code writes — uses Write tool to create .md files directly in output directory
Wikigen validates — checks for file creation and size, retries on failure, logs errors

This delegation model ensures that accurate, evidence-based documentation is generated through thorough code analysis rather than templating, guessing, or speculation.

Related Pages

Architecture & Design — Overall system architecture and two-phase generation pipeline
Wiki Generation Processing Flow — Detailed analysis of prompts and XML parsing logic
CLI Usage & Commands — Command-line flags including -model, -pp, and -local
Configuration & Environment — Environment variables like CLAUDE_MODEL and WIKI_PAGE_PARALLEL
Error Handling & Retry Mechanism — Retry strategy, error logging, and partial result preservation
Parallel Processing & Performance — Concurrency control, semaphore patterns, and performance tuning
System Overview — Project purpose and design philosophy

Home

Claude Code Integration

Claude Code Integration

Overview of Claude Code Integration

Claude Code Invocation

The claudeCall Function

Command-Line Arguments

Repository Directory Resolution

System Prompts and Prompt Engineering

XML System Prompt (Structure Phase)

Structure Determination Prompt

Page Generation Prompt

Tool Interaction Patterns

Read Tool

Grep Tool

Glob Tool

Bash Tool

Two-Phase Generation Flow

Phase 1: Structure Determination

Phase 2: Page Generation

Mermaid Diagram: Two-Phase Generation Flow

Invocation Sequence Diagram

Error Handling and Output Control

Output Format Control

File Detection and Retry

Error Logging

Parallel Invocation and Concurrency

Model Selection and Configuration

Working Directory and Relative Paths

Requirements and Dependencies

Summary: Tool Interaction Pattern

Related Pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!