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: 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.

• 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.

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.

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.

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

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

python install.py and codeboarding-setup download language server binaries to ~/.codeboarding/servers/, shared across projects. 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.

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)
# 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.

Two environment variables tune the static analysis itself:

# Analyze a local repository
python main.py 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 main.py full --local ./my-project --depth-cap 5

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

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

# Analyze a remote GitHub repository
python main.py 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.

• 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.

• Languages: Python, TypeScript, JavaScript, Java, Go, PHP, Rust, C#.
• LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, Requesty, LiteLLM proxy, and more.

• 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.

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.

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.

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