CodeBoarding

CodeBoarding generates interactive architectural diagrams from any codebase using static analysis + LLM agents. It's built for developers and AI agents that need to understand large, complex systems quickly.

• Extracts modules and relationships via control flow graph analysis (LSP-based, no runtime required)
• Builds layered abstractions with an LLM agent (OpenAI, Anthropic, Google Gemini, Ollama, and more)
• Outputs Mermaid.js diagrams ready for docs, IDEs, and CI/CD pipelines

Supported languages: Python · TypeScript · JavaScript · Java · Go · PHP

Requirements

• Python 3.12 or 3.13 — other versions are currently not supported.

Installation

The recommended way to install the CLI is with pipx, which automatically creates an isolated environment:

pipx install codeboarding --python python3.12 --pip-args="--extra-index-url https://pip.codeboarding.org/simple/"

Alternatively, install into an existing virtual environment with pip:

pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/

Installing into the global Python environment with pip is not recommended — it can cause dependency conflicts and will fail if the system Python is not 3.12 or 3.13.

Language server binaries are downloaded automatically on first use. To pre-install them explicitly (useful in CI or restricted environments):

codeboarding-setup

npm is required (used for Python, TypeScript, JavaScript, and PHP language servers). If npm is not found, it will be automatically installed during the setup. Binaries are stored in ~/.codeboarding/servers/ and shared across all projects.

Quick Start

CLI

# Analyze a local repository (output goes to /path/to/repo/.codeboarding/)
codeboarding full --local /path/to/repo

# Analyze a remote GitHub repository (cloned to cwd/repo_name/, output to cwd/repo_name/.codeboarding/)
codeboarding full https://github.com/user/repo

To explore the result interactively, open the web platform and load the generated .codeboarding/analysis.json — it is parsed in your browser, nothing is uploaded.

Python API

import json
from pathlib import Path
from diagram_analysis import DiagramGenerator, RunContext, configure_models
from diagram_analysis.analysis_json import parse_unified_analysis

# Pass the key programmatically — shell env vars always take precedence if already set.
# Use the env-var name for whichever provider you want:
#   OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, OLLAMA_BASE_URL, …
configure_models(api_keys={"OPENAI_API_KEY": "sk-..."})

repo_path = Path("/path/to/repo")
output_dir = repo_path / ".codeboarding"
output_dir.mkdir(parents=True, exist_ok=True)

# Generate the architectural diagram
context = RunContext.resolve("my-project")
generator = DiagramGenerator(
    repo_location=repo_path,
    temp_folder=output_dir,
    repo_name="my-project",
    output_dir=output_dir,
    depth_cap=3,  # Maximum hierarchy depth for automatic expansion, not a target.
    run_id=context.run_id,
    log_path=context.log_path,
)
analysis_path = generator.generate_analysis()

# Read and inspect the results
with open(analysis_path) as f:
    data = json.load(f)

root, sub_analyses = parse_unified_analysis(data)

print(root.description)
for comp in root.components:
    print(f"  {comp.name}: {comp.description}")
    if comp.component_id in sub_analyses:
        for sub in sub_analyses[comp.component_id].components:
            print(f"    └ {sub.name}")

Configuration

LLM provider keys and model overrides are stored in ~/.codeboarding/config.toml, created automatically on first run:

# ~/.codeboarding/config.toml

[provider]
# Uncomment exactly one provider key
# openai_api_key    = "sk-..."
# anthropic_api_key = "sk-ant-..."
# google_api_key    = "AIza..."
# ollama_base_url   = "http://localhost:11434"

# Optional Anthropic endpoint override; requires anthropic_api_key above
# anthropic_base_url = "https://resource.services.ai.azure.com/anthropic"

[llm]
# Optional: override the default model for your active provider
# agent_model = "gemini-3.8-flash"

Shell environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) always take precedence over the config file, so CI/CD pipelines need no changes. For private repositories, set GITHUB_TOKEN in your environment.

Tip: Google Gemini 3 Pro consistently produces the best diagram quality for complex codebases.

CLI Reference

codeboarding full [REPO_URL ...]           # remote: clone + analyze
codeboarding full --local PATH             # local: analyze in-place
codeboarding full --local PATH --render FORMAT # render md/html/mdx/rst after analysis
codeboarding incremental --local PATH      # re-analyze only changed parts
codeboarding partial --local PATH --component-id ID   # update one component
codeboarding-render PATH/analysis.json --format FORMAT # render an existing analysis

Integrations

• VS Code Extension — browse diagrams directly in your IDE
• GitHub Action — generate docs on every push
• MCP Server — serve concise architecture docs to AI coding assistants (Claude Code, Cursor, etc.)

Links

• Source code
• Example diagrams (800+ open-source projects)
• Architecture documentation
• Discord community