AI Documentation Generator

An AI-powered code documentation generator that automatically analyzes repositories and creates comprehensive documentation using large language models. The system employs a multi-agent architecture: five specialized analysis agents run concurrently to map a codebase's structure, dependencies, data flow, request flow, and APIs, and generation agents turn those analyses into a polished README.md and AI assistant configuration files (CLAUDE.md, AGENTS.md, .cursor/rules/). A GitLab cronjob mode discovers active projects and opens merge requests with fresh analysis automatically.

📝 Blog Posts

Read the full story behind this project:

• 🇺🇸 English: Docs That Don’t Rot: How Multi-Agent AI Rewrote Our Workflow
• 🇮🇷 از دستیار کدنویس تا همکار هوشمند؛ گام اول: کابوس مستندسازی

Table of Contents

• Features
• Installation
• Quick Start
• Usage
• Configuration
• Architecture
• License

Features

• Multi-Agent Analysis: Five specialized AI agents for code structure, data flow, dependency, request flow, and API analysis, writing reusable analysis documents to .ai/docs/
• Automated Documentation: Generates comprehensive README files with configurable sections
• AI Assistant Configuration: Generates CLAUDE.md, AGENTS.md, and .cursor/rules/*.mdc files for AI coding assistants
• Claude Code Plugin & Skills: Ships as an installable Claude Code plugin with analyze-codebase, generate-readme, and generate-ai-rules skills (.claude-plugin/, skills/)
• GitLab Integration: Cronjob mode discovers recently active GitLab projects, runs analysis, and opens merge requests
• Concurrent Processing: Parallel agent execution with a configurable worker pool (ANALYZER_MAX_WORKERS, 0 = auto-detect CPU count)
• Flexible Configuration: Layered configuration — Pydantic defaults, .ai/config.yaml, then CLI flags
• Multiple LLM Support: Works with any OpenAI-compatible API (OpenAI, Anthropic-compatible gateways, OpenRouter, local models, etc.), with per-agent model/endpoint settings
• Resilience: Agent-level retries plus an HTTP retry client with exponential backoff and Retry-After support (handles 429s)
• Observability: OpenTelemetry tracing via logfire with optional Langfuse integration

Installation

Using Skills (Claude Code)

This repository doubles as a Claude Code plugin — the easiest way to use it, no API keys or Python setup required. Install it from within Claude Code:

/plugin marketplace add divar-ir/ai-doc-gen
/plugin install ai-doc-gen@divar

This adds three skills that Claude Code invokes directly:

• analyze-codebase — multi-agent analysis producing .ai/docs/ documents
• generate-readme — README generation from analysis or direct exploration
• generate-ai-rules — CLAUDE.md, AGENTS.md, and Cursor rules generation

Prerequisites

• Python 3.13
• Git
• API access to an OpenAI-compatible LLM provider

1. Clone the repository:

git clone https://github.com/divar-ir/ai-doc-gen.git
cd ai-doc-gen

2. Install using uv (recommended):

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

3. Or install with pip:

pip install -e .

A Dockerfile and a Helm chart (k8s/helm/) are also provided for containerized and scheduled (Kubernetes CronJob) deployments.

Quick Start

1. Set up your environment and configuration:

# Copy and edit environment variables (LLM API keys, base URLs, etc.)
cp .env.sample .env

# Copy and edit configuration
mkdir -p .ai
cp config_example.yaml .ai/config.yaml

2. Run analysis and generate documentation:

# Analyze your repository
uv run src/main.py analyze --repo-path .

# Generate README documentation
uv run src/main.py generate readme --repo-path .

# Generate AI assistant configuration files (CLAUDE.md, AGENTS.md, .cursor/rules/)
uv run src/main.py generate ai-rules --repo-path .

Analysis documents are saved to .ai/docs/, and generated documentation and AI configuration files are placed in your repository root.

Usage

Available Commands

# Analyze codebase (structure, data flow, dependencies, request flow, APIs)
uv run src/main.py analyze --repo-path 

# Generate README documentation
uv run src/main.py generate readme --repo-path 

# Generate AI assistant configuration files
uv run src/main.py generate ai-rules --repo-path 

# Run cronjob (GitLab batch analysis)
uv run src/main.py cronjob analyze

The package also installs an ai-doc-gen console script exposing the same CLI.

Advanced Options

Analysis Options:

# Analyze with specific exclusions
uv run src/main.py analyze --repo-path . --exclude-code-structure --exclude-data-flow

# Limit concurrent analyzer agents
uv run src/main.py analyze --repo-path . --max-workers 2

# Use custom configuration file
uv run src/main.py analyze --repo-path . --config /path/to/config.yaml

README Generation Options:

# Generate with specific section exclusions
uv run src/main.py generate readme --repo-path . --exclude-architecture --exclude-c4-model

# Use existing README as context
uv run src/main.py generate readme --repo-path . --use-existing-readme

AI Rules Generation Options:

# Skip overwriting existing files
uv run src/main.py generate ai-rules --repo-path . \
    --skip-existing-claude-md \
    --skip-existing-agents-md \
    --skip-existing-