Getting Started with open-auto-doc

Prerequisites

• Node.js 18 or higher
• GitHub account (public or private repos supported)
• Anthropic API key from https://console.anthropic.com/

Installation

Installation Methods

Option 1: Use with npx (Recommended for one-time use)

No installation required. Run directly:

npx @latent-space-labs/open-auto-doc

Option 2: Install globally (Recommended for repeated use)

npm install -g @latent-space-labs/open-auto-doc

Once installed globally, you can run the open-auto-doc command from anywhere without the npx prefix.

Verify Installation

open-auto-doc --help

This displays all available commands and options.

For Development/Contributing

Clone the repository and build from source:

git clone https://github.com/Latent-Space-Labs/open-auto-doc.git
cd open-auto-doc
npm install
npm run build

After building, run the CLI locally:

node packages/cli/dist/index.js --help

Quick Start

Step 1: Generate Documentation

Run the interactive setup:

npx @latent-space-labs/open-auto-doc

The CLI guides you through the entire process:

1. GitHub OAuth Login — Authenticates with your GitHub account (opens browser, no tokens to copy)
2. Select Repositories — Choose which repos you want to document
3. Enter Anthropic API Key — Paste your API key from https://console.anthropic.com/
4. AI Analysis — The system analyzes your codebase and generates comprehensive docs
5. Site Generation — A complete Next.js documentation site is created

The process outputs progress updates:

┌  open-auto-doc — AI-powered documentation generator
│
◆  Let's connect your GitHub account.
│  → Opens browser for GitHub OAuth
│
◇  Found 47 repositories
◇  Select repositories to document
│  my-api, my-frontend, shared-lib
│
◇  Enter your Anthropic API key
│  sk-ant-...
│
◇  [my-api] Analyzing architecture...
◇  [my-api] Found 14 endpoints, 5 models
◇  [my-frontend] Analyzing architecture...
◇  [my-frontend] Found 23 components
│
◇  Site scaffolded
◇  Documentation content written
│
└  Documentation generated successfully!

Step 2: Preview Locally

Navigate to the generated site directory and start the development server:

cd docs-site
npm install
npm run dev

Open http://localhost:3000 in your browser to preview your documentation site.

Step 3: Deploy to Vercel

Deploy the docs site:

open-auto-doc deploy

This command:

• Creates a GitHub repository for your docs
• Pushes the generated site to the repository

Then:

1. Visit https://vercel.com/new
2. Import the newly created docs repository
3. Click Deploy

Your documentation is now live with a public URL!

Step 4: Set Up Auto-Updates (Optional)

Enable automatic documentation updates whenever you push code:

open-auto-doc setup-ci

This adds a GitHub Actions workflow to your source repository. The workflow will:

• Trigger on every push to main (configurable)
• Re-analyze your code using the AI engine
• Update the documentation site automatically
• Deploy changes via Vercel

You need to add two secrets to your source repo (Settings → Secrets → Actions):

• ANTHROPIC_API_KEY — Your Anthropic API key
• DOCS_DEPLOY_TOKEN — A GitHub Personal Access Token with repo scope (create at https://github.com/settings/tokens/new)

Configuration

Configuration Files

.autodocrc.json (Generated Automatically)

After running the initial setup, a configuration file is created that stores:

• Repository information (owner, names, branches)
• Analysis settings
• Output directory location

Note: This file is used by the generate command to re-analyze without repeating the full setup.

Environment Variables

Required

• ANTHROPIC_API_KEY — Your Anthropic API key from https://console.anthropic.com/
  • Used for AI code analysis
  • Only sent to Anthropic's API, never to other services
  • Required for all analysis operations

Optional

• OPEN_AUTO_DOC_GITHUB_CLIENT_ID — Custom GitHub OAuth App client ID
  • If not set, uses the default open-auto-doc OAuth app
  • Useful if you want to use your own GitHub App
  • Set this environment variable before running the CLI

Credential Storage

Credentials are stored locally:

• Location: ~/.open-auto-doc/credentials.json
• Permissions: 0600 (read/write for owner only)
• Contents: GitHub OAuth tokens and session data

Security: Your Anthropic API key is not stored locally. Enter it each time or set the ANTHROPIC_API_KEY environment variable.

Commands Reference

Site Configuration

The generated docs site is built with Fumadocs v16 and Next.js. Configuration happens in the generated docs-site/:

• source.config.ts — MDX processing and Fumadocs settings
• tailwind.config.ts — Tailwind CSS customization
• next.config.js — Next.js configuration

Refer to Fumadocs documentation for detailed customization options.

Examples

Common Usage Patterns

Example 1: Document a Single Repository

# Start the interactive setup
npx @latent-space-labs/open-auto-doc

# When prompted:
# 1. Authorize with GitHub
# 2. Select your single repository
# 3. Enter Anthropic API key
# 4. Wait for analysis to complete

Example 2: Document Multiple Repositories Together

npx @latent-space-labs/open-auto-doc

# When prompted to select repositories, choose multiple:
# ✔ my-api
# ✔ my-frontend
# ✔ shared-utils

# The generated site will include:
# - Separate docs for each repo
# - Cross-repo analysis (shared dependencies, API contracts)
# - Relationship diagrams between services

Example 3: Custom Output Directory

npx @latent-space-labs/open-auto-doc init -o my-custom-docs

Generated site will be created in my-custom-docs/ instead of the default docs-site/.

Example 4: Regenerate Documentation

After the initial setup, update docs without re-running full authentication:

# Re-analyze everything
open-auto-doc generate

# Or only re-analyze changed files (faster)
open-auto-doc generate --incremental

This uses the .autodocrc.json configuration created during initial setup.

Example 5: Set Up CI/CD Pipeline

# After initial generation, set up automatic updates
open-auto-doc setup-ci

# Add these secrets to your source repo:
# ANTHROPIC_API_KEY = sk-ant-...
# DOCS_DEPLOY_TOKEN = ghp_...

# Now every push to main will:
# 1. Trigger GitHub Actions
# 2. Re-analyze your code
# 3. Update documentation site
# 4. Auto-deploy via Vercel

Example 6: Improve Documentation with CLAUDE.md

Create a CLAUDE.md file in your repository to provide context to the AI:

# CLAUDE.md

## Architecture
This is a FastAPI backend with async endpoints and WebSocket support.

## Key Patterns
- All database queries use SQLAlchemy ORM
- API endpoints are organized by feature area
- Authentication uses JWT tokens in Authorization header

## Tech Stack
- FastAPI 0.104+
- PostgreSQL with Alembic migrations
- Pydantic v2 for validation

Place this file in your repo root or .claude/ directory. The AI analyzer will use it to generate more accurate documentation.

Example 7: Login and Logout

# Authenticate with GitHub separately
open-auto-doc login

# Clear all stored credentials
open-auto-doc logout

Example 8: Deploy Generated Docs

# Create GitHub repo and push docs
open-auto-doc deploy

# Then:
# 1. Go to https://vercel.com/new
# 2. Import the created repository
# 3. Click Deploy
# 4. Your docs are live!

# After initial deployment, Vercel auto-deploys on every push

Generated Documentation Includes

The AI analyzer generates the following documentation sections:

Architecture Overview

• Tech stack and major dependencies
• Module breakdown with data flow diagrams
• Entry points and key patterns
• Mermaid architecture diagrams

Getting Started Guide

• Prerequisites and installation steps
• Quick start instructions
• Configuration options
• Common examples

API Reference

• All endpoints with HTTP methods
• Request and response schemas
• Query parameters and body payloads
• Authentication requirements
• Example requests and responses

UI Components (if applicable)

• Component props and types
• Usage examples
• Categories and organization
• Visual previews

Data Models

• Field types and constraints
• Relationships between models
• Entity-relationship diagrams (Mermaid)
• Usage examples

Language Support

Works with any programming language:

• TypeScript, JavaScript, Python, Go, Rust
• Java, Kotlin, Ruby, PHP, C#, Swift, and more

The analyzer uses Claude AI to understand code semantically, not language-specific parsers.