CodeBoarding

Review the change, not the diff.

See what a pull request does to your system before you merge it. CodeBoarding turns code into interactive architecture maps so you can explore components, follow their dependencies, and review analyzed pull requests alongside code diffs.

This repository contains the open-source analysis engine and CLI. Static analysis extracts code relationships; language models help name and describe the components. Use the resulting map in the web platform, your editor, CI, or generated documentation.

Discord · VS Code extension · Open VSX extension · Web platform · Website · Getting started

The website's illustrative animation (plays once, about 18 seconds). View the static map or replay the interactive story on the website.

The example starts with a large pull-request diff, then shows the six components it touches. Identity and Payments have changed: a new dependency means a Google sign-in outage can block card payments.

Explore the system. Review the change

• Explore: start with the architecture map, expand components, and navigate to the source behind them. Open prepared public repositories without signing in.
• Review: see changed components and dependencies, read changes grouped by component, and inspect code diffs. PR review requires an available analysis from the GitHub Action; architecture comparisons also need a baseline.
• Bring your own analysis: open an analysis.json or compare two local analysis files. Files are parsed and compared in your browser.
• Share context: use component descriptions and diagrams in documentation, reviews, and your coding agent's next prompt.

What CodeBoarding generates

• An analysis.json containing the architecture, component descriptions, relationships, and source references.
• Nested component diagrams for exploring subsystems.
• Markdown with Mermaid diagrams, HTML, MDX, or reStructuredText documentation when you request rendering.
• Incremental updates against a previous analysis, or updates to a selected component.

How it works

1. Analyze the code. The engine scans the repository and extracts symbols and relationships with static analysis.
2. Build the map. It groups code into components and uses your configured model provider to describe their responsibilities. Analysis can send code excerpts to that provider.
3. Explore or review. Load the analysis in the web platform or editor, render it as documentation, or use the GitHub Action to publish architecture changes on pull requests.

The engine's top-level architecture, generated from the committed analysis dated September 21, 2026:

graph LR
    Static_Analysis_Engine["Static Analysis Engine"]
    Diagram_Generation_and_Health_Orchestration["Diagram Generation and Health Orchestration"]
    LLM_Planning_and_Analysis_Agents["LLM Planning and Analysis Agents"]
    CLI_Workflows_and_Output_Generators["CLI, Workflows, and Output Generators"]
    Repository_and_File_Utilities["Repository and File Utilities"]
    Application_Entry_Points_and_Runtime_Configuration["Application Entry Points and Runtime Configuration"]
    Execution_Monitoring_and_Metrics["Execution Monitoring and Metrics"]
    Tool_Registry_and_Environment_Installer["Tool Registry and Environment Installer"]
    Static_Analysis_Engine -- "tracks telemetry events" --> Diagram_Generation_and_Health_Orchestration
    Static_Analysis_Engine -- "checks repository ignores and git changes" --> Repository_and_File_Utilities
    Static_Analysis_Engine -- "locates tool binaries and runtime directories" --> Tool_Registry_and_Environment_Installer
    Static_Analysis_Engine -- "builds agent insight models" --> LLM_Planning_and_Analysis_Agents
    Static_Analysis_Engine -- "formats cluster identifiers" --> Application_Entry_Points_and_Runtime_Configuration
    Diagram_Generation_and_Health_Orchestration -- "queries static analysis graphs and specs" --> Static_Analysis_Engine
    Diagram_Generation_and_Health_Orchestration -- "configures LLMs and models file index entries" --> LLM_Planning_and_Analysis_Agents
    Diagram_Generation_and_Health_Orchestration -- "normalizes paths and checks git changes" --> Repository_and_File_Utilities
    Diagram_Generation_and_Health_Orchestration -- "resolves cluster hierarchy and ordering" --> Application_Entry_Points_and_Runtime_Configuration
    Diagram_Generation_and_Health_Orchestration -- "initializes stats writers and logs runs" --> Execution_Monitoring_and_Metrics
    Diagram_Generation_and_Health_Orchestration -- "executes plugin health checks" --> CLI_Workflows_and_Output_Generators
    LLM_Planning_and_Analysis_Agents -- "reads call graph edges and nodes" --> Static_Analysis_Engine
    LLM_Planning_and_Analysis_Agents -- "filters repository files and normalizes paths" --> Repository_and_File_Utilities
    LLM_Planning_and_Analysis_Agents -- "checks cluster hierarchy and loads user configuration" --> Application_Entry_Points_and_Runtime_Configuration
    LLM_Planning_and_Analysis_Agents -- "attaches monitoring callbacks and mixins" --> Execution_Monitoring_and_Metrics
    CLI_Workflows_and_Output_Generators -- "resolves execution context and loads analysis metadata" --> Diagram_Generation_and_Health_Orchestration
    CLI_Workflows_and_Output_Generators -- "initializes LLM credentials and computes source hashes" --> LLM_Planning_and_Analysis_Agents
    CLI_Workflows_and_Output_Generators -- "manages ignore files and repository git operations" --> Repository_and_File_Utilities
    CLI_Workflows_and_Output_Generators -- "loads user configuration and sets up logging" --> Application_Entry_Points_and_Runtime_Configuration
    CLI_Workflows_and_Output_Generators -- "wraps workflow execution in monitoring context" --> Execution_Monitoring_and_Metrics
    CLI_Workflows_and_Output_Generators -- "ensures required tool binaries are installed" --> Tool_Registry_and_Environment_Installer
    CLI_Workflows_and_Output_Generators -- "retrieves node type definitions for output rendering" --> Static_Analysis_Engine
    Repository_and_File_Utilities -- "builds tool configurations from manifest" --> Tool_Registry_and_Environment_Installer
    Repository_and_File_Utilities -- "reads fingerprint data for change detection" --> Diagram_Generation_and_Health_Orchestration
    Repository_and_File_Utilities -- "hashes repository source files for fingerprint comparison" --> LLM_Planning_and_Analysis_Agents
    Application_Entry_Points_and_Runtime_Configuration -- "loads analysis metadata and resolves run context" --> Diagram_Generation_and_Health_Orchestration
    Application_Entry_Points_and_Runtime_Configuration -- "triggers incremental analysis and renders documentation formats" --> CLI_Workflows_and_Output_Generators
    Application_Entry_Points_and_Runtime_Configuration -- "clones and checks out repositories in temporary folders" --> Repository_and_File_Utilities
    Execution_Monitoring_and_Metrics -- "resolves project root directory for monitoring storage" --> Repository_and_File_Utilities
    Tool_Registry_and_Environment_Installer -- "inspects language definitions and runtime environments" --> Static_Analysis_Engine
    Tool_Registry_and_Environment_Installer -- "locates executable runnables and initializes configuration templates" --> Application_Entry_Points_and_Runtime_Configuration

For the engine's own architecture, open its interactive map.

Quick start

To try the product without installing anything, open a public map. To connect your own repositories, sign in to the web platform and choose which repositories CodeBoarding can access. See the getting-started guide for the GitHub and editor workflows.

To run the analysis engine yourself, use either option below. Both require Python 3.12 and a configured model provider.

Run from source

git clone https://github.com/CodeBoarding/CodeBoarding.git
cd CodeBoarding
uv sync --frozen
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python -m infra.install
python -m codeboarding_cli.main full --local /path/to/repo

Use the packaged CLI

The recommended install method is pipx, which keeps the CLI in its own isolated environment:

pipx install codeboarding --python python3.12
codeboarding-setup
codeboarding full --local /path/to/repo

Or, if you prefer pip, install into a virtual environment (not the global Python):

pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
codeboarding-setup
codeboarding full --local /path/to/repo

Output is written to /path/to/repo/.codeboarding/. To explore it interactively, open the web platform and load the generated analysis.json through the viewer's Switch source → File picker. Local analysis files are parsed and compared in your browser; this is separate from generating the analysis with your configured model provider.

To also generate overview and one file per expanded component, pass --render with one of md, html, mdx, or rst. Rendering is available after full, incremental, and partial local analyses; previously generated files for the selected format are reconciled from a renderer-owned manifest:

codeboarding full --local /path/to/repo --render md
codeboarding incremental --local /path/to/repo --render html
codeboarding partial --local /path/to/repo --component-id "1.2" --render rst

You can render an existing analysis without rerunning analysis or configuring an LLM:

codeboarding-render /path/to/repo/.codeboarding/analysis.json
# Select a format or output directory:
codeboarding-render /path/to/analysis.json --format mdx --output-dir /path/to/docs

# From a source checkout in development:
python codeboarding_cli/render.py ../../demo/markitdown/.codeboarding/analysis.json --format md

An analysis downloads the language servers its repository's languages need into ~/.codeboarding/servers/ the first time it needs them, shared across projects; python -m infra.install and codeboarding-setup download all of them up front. Node.js (and its bundled npm) is required for the Python, TypeScript, JavaScript, and PHP language servers; if neither node nor CODEBOARDING_NODE_PATH is set, setup downloads a pinned Node.js runtime into ~/.codeboarding/servers/nodeenv/ automatically.

Configuration

On first run, CodeBoarding creates ~/.codeboarding/config.toml. Set one provider there or use environment variables.

[provider]
# openai_api_key            = "sk-..."
# openai_base_url           = "https://api.example.com/v1"  # any OpenAI-compatible gateway
# anthropic_api_key         = "sk-ant-..."
# anthropic_base_url        = "https://resource.services.ai.azure.com/anthropic"  # Azure Foundry
# google_api_key            = "AIza..."
# vercel_api_key            = "vck_..."
# aws_bearer_token_bedrock  = "..."
# ollama_base_url           = "http://localhost:11434"
# openrouter_api_key        = "sk-..."
# orcarouter_api_key        = "sk-orca-..."   # model routing gateway (https://www.orcarouter.ai)
# requesty_api_key          = "rqsty-..."     # LLM gateway (https://www.requesty.ai)
# opper_api_key             = "..."           # EU-hosted AI gateway (https://opper.ai)
# litellm_base_url          = "http://localhost:4000"  # LiteLLM proxy server URL (required)
# litellm_api_key           = "sk-..."           # LiteLLM proxy server key (optional)

[llm]
# agent_model = "gemini-3.8-flash"

openai_base_url points CodeBoarding at any OpenAI-compatible gateway, including LM Studio. Set its model ID with agent_model; CodeBoarding adapts its prompts for the model families already represented by its provider defaults, including Qwen. The equivalent shell variables are OPENAI_BASE_URL, OPENAI_API_KEY, and AGENT_MODEL.

anthropic_base_url points the Anthropic client at a compatible Messages API, including Azure Foundry Claude deployments. Set the deployment key as anthropic_api_key and use canonical Anthropic model IDs such as claude-sonnet-5 for agent_model so CodeBoarding selects the correct model capabilities and prompts.

Shell environment variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and OLLAMA_BASE_URL take precedence over the config file. For private repositories, set GITHUB_TOKEN in your environment.

Three environment variables tune the static analysis itself:

Variable	Effect
CODEBOARDING_LSP_REQUEST_TIMEOUT	Seconds a language-server request may block when it uses the per-language default (120s for C# and Kotlin, 60s elsewhere). Not a hard cap on every request: initialize has its own startup budget (the request default), Kotlin's build import is awaited separately (up to 1800s), and the indexing and didOpen-drain probes pass their own scaled budget (60s plus 2s per file, capped at 1800s); neither is affected. Applies to every language in the run. Unset or empty leaves the defaults alone; any other unusable value fails the run rather than falling back.
CODEBOARDING_MAX_CONCURRENT_ENGINES	How many language servers an analysis runs at once. Unset or 0, the CLI and the GitHub Action run one at a time, each stopped when its language is done, and the editor keeps one per project running. Set, the editor's servers also start only for an analysis, so its file queries are unavailable.
CODEBOARDING_LSP_MEMORY_BUDGET_MB	Megabytes the language servers running at once share; tsserver's heap is its share less 512. Unset, it is three quarters of the machine's memory (or of a cgroup v2 container's limit, when lower), at most 12 GB.

Common commands

# Analyze a local repository
python -m codeboarding_cli.main full --local ./my-project

# Raise the depth ceiling to auto-expand deeper (rarely needed — a component that
# outgrows the leaf ceiling is flagged expandable at whatever depth the run stops
# and can be expanded on demand; --depth-cap is a safety-valve cap, default 3)
python -m codeboarding_cli.main full --local ./my-project --depth-cap 5

# Re-analyze only changed parts when possible
python -m codeboarding_cli.main incremental --local ./my-project

# Update a single component by ID
python -m codeboarding_cli.main partial --local ./my-project --component-id "1.2"

# Analyze a remote GitHub repository
python -m codeboarding_cli.main full https://github.com/pytorch/pytorch

--depth-cap configures metadata.depth_cap; metadata.depth_level records the depth actually reached. The cap is a maximum, not a target depth. --depth-level is rejected; there is no compatibility alias.

Python callers must use run_full(..., depth_cap=...), build_generator(..., depth_cap=...), and DiagramGenerator(..., depth_cap=...). The generator attribute is depth_cap and the exported default is diagram_analysis.DEFAULT_DEPTH_CAP (3). The GitHub helper uses DIAGRAM_DEPTH_CAP and rejects DIAGRAM_DEPTH_LEVEL. Telemetry reports configured depth_cap, not depth_level. Readers of analysis results must keep reading metadata.depth_level for the actual depth. Existing baseline loading behavior is unchanged: prefer metadata.depth_cap, fall back to legacy metadata.depth_level, then use DEFAULT_DEPTH_CAP if neither exists. This metadata fallback is not a CLI alias.

Incremental needs a baseline. incremental diffs the working tree against the previous analysis in .codeboarding/ (analysis.json + fingerprint.json). That baseline can live purely locally — a prior full/incremental run in the same output dir is enough. Commit .codeboarding/ only if you want the baseline to travel with the branch (so a teammate or a fresh checkout can run incremental too). With no baseline at all — or one that predates content versioning — incremental fails fast with "run a full analysis first" rather than silently doing a full run. Static-analysis caches are versioned but not migrated; after a cache-version upgrade, run a full analysis once to reindex.

Where to use it

• CLI: CodeBoarding CLI — this repository — for local analysis, automation, and documentation generation.
• Browser: web platform for Explore and Review, public maps, and local analysis files.
• Editor: VS Code Marketplace or Open VSX for in-editor architecture exploration.
• CI: GitHub Action to keep analysis updated and post architecture change maps on pull requests.

Supported stack

• Languages: Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, C#.
  • Java needs a JDK (21 recommended).
  • Kotlin is analysed with JetBrains' kotlin-lsp (about 360 MB with its own Java runtime, under the JetBrains Free Plugin License) and needs glibc 2.34 or newer on Linux. Kotlin calls into Java are not drawn yet.
• LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, Requesty, Opper, LiteLLM proxy, and more.

Examples

• Explore CodeBoarding's architecture — the engine, drawn from its own code.
• Review CodeBoarding pull request #586 — component changes and code diffs together.
• Browse example diagrams.
• Awesome Architecture MDs — generated architecture documentation for open-source repositories (formerly GeneratedOnBoardings).

Public maps need a committed .codeboarding/analysis.json at the selected branch or commit. Open one at https://app.codeboarding.org/<owner>/<repo> without signing in; opening a URL does not generate a new analysis.

Telemetry

CodeBoarding collects usage telemetry (which command ran, success/failure, duration, token cost, repository size and languages, and the account the repository belongs to) to help us improve the tool. It is on by default and never collects source code, file names, repository names, paths, prompts, model outputs, or API keys. Opt out anytime:

export CODEBOARDING_TELEMETRY=false   # or: export DO_NOT_TRACK=1

See TELEMETRY.md for the full list of events and properties.

Contributing

If you want to improve CodeBoarding, open an issue or send a pull request. We welcome improvements to analysis quality, output generators, integrations, and developer experience.

See CONTRIBUTING.md for development setup and testing guidance.

License

The analysis engine and CLI in this repository are released under the MIT License.