About ai-doc-gen

AI-powered multi-agent system that automatically analyzes codebases and generates comprehensive documentation. Features GitLab integration, concurrent processing, and multiple LLM support for better code understanding and developer onboarding.

d

Published by

divar-ir

Visit View Profile

README.md

View on GitHub

AI Documentation Generator

An AI-powered code documentation generator that automatically analyzes repositories and creates comprehensive documentation using advanced language models. The system employs a multi-agent architecture to perform specialized code analysis and generate structured documentation.

📝 Blog Posts

Read the full story behind this project:

Features

Multi-Agent Analysis: Specialized AI agents for code structure, data flow, dependency, request flow, and API analysis
Automated Documentation: Generates comprehensive README files with configurable sections
AI Assistant Configuration: Automatically generates CLAUDE.md, AGENTS.md, and .cursor/rules/ files for AI coding assistants
GitLab Integration: Automated analysis for GitLab projects with merge request creation
Concurrent Processing: Parallel execution of analysis agents for improved performance
Flexible Configuration: YAML-based configuration with environment variable overrides
Multiple LLM Support: Works with any OpenAI-compatible API (OpenAI, OpenRouter, local models, etc.)
Observability: Built-in monitoring with OpenTelemetry tracing and Langfuse integration

Installation

Prerequisites

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

Clone the repository:

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

Install using uv (recommended):

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

Or install with pip:
```
pip install -e .
```

Quick Start

Set up your environment and configuration:


# Copy and edit environment variables
cp .env.sample .env

Copy and edit configuration

mkdir -p .ai cp config_example.yaml .ai/config.yaml


2. Run analysis and generate documentation:
```bash
# 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 .

Generated documentation will be saved to .ai/docs/ directory, and AI configuration files will be placed in your repository root.

Usage

Available Commands

# Analyze codebase
uv run src/main.py analyze --repo-path <path>

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

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

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

Advanced Options

Analysis Options:

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

# 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-cursor-rules

# Customize detail level and line limits
uv run src/main.py generate ai-rules --repo-path . \
    --detail-level comprehensive \
    --max-claude-lines 600 \
    --max-agents-lines 150

Configuration

The tool automatically looks for configuration in .ai/config.yaml or .ai/config.yml in your repository.

Configuration Options

Exclude specific analyses: Skip code structure, data flow, dependencies, request flow, or API analysis
Customize README sections: Control which sections appear in generated documentation
Configure cronjob settings: Set working paths and commit recency filters

You can use CLI flags for quick configuration overrides. See config_example.yaml for all available options and .env.sample for environment variables.

Architecture

The system uses a multi-agent architecture with specialized AI agents for different types of code analysis and generation:

CLI Layer: Entry point with command parsing and subcommand routing
Handler Layer: Command-specific business logic (analyze, generate, cronjob)
Agent Layer: AI-powered analysis and documentation generation
- Analyzer agents: Structure, data flow, dependencies, request flow, API analysis
- Documentation agent: README generation
- AI Rules generator: CLAUDE.md, AGENTS.md, and Cursor rules generation
Tool Layer: File system operations and utilities

Technology Stack

Python 3.13 with pydantic-ai for AI agent orchestration
OpenAI-compatible APIs for LLM access (OpenAI, OpenRouter, etc.)
GitPython & python-gitlab for repository operations
OpenTelemetry & Langfuse for observability
YAML + Pydantic for configuration management

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with pydantic-ai for AI agent orchestration
Supports multiple LLM providers through OpenAI-compatible APIs (including OpenRouter)
Uses Langfuse for LLM observability

ai-doc-gen