Skip to content

PYPI.md

Latest commit

 

History

History
165 lines (116 loc) · 6.16 KB

PYPI.md

File metadata and controls

165 lines (116 loc) · 6.16 KB
Raw

CodeBoarding

Website Discord GitHub

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

Python API

import json
from pathlib import Path
from diagram_analysis import DiagramGenerator, 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
generator = DiagramGenerator(
    repo_location=repo_path,
    temp_folder=output_dir,
    repo_name="my-project",
    output_dir=output_dir,
    depth_level=1,
)
[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"

[llm]
# Optional: override the default model for your active provider
# agent_model   = "gemini-3-flash"
# parsing_model = "gemini-3-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 incremental --local PATH      # re-analyze only changed parts
codeboarding partial --local PATH --component-id ID   # update one component
Option Description
--local PATH Analyze a local repository (output: PATH/.codeboarding/)
--depth-level INT Diagram depth (default: 1)
--force (full only) Force full reanalysis, skip cached static analysis
--base-ref REF / --target-ref REF (incremental only) Git refs to diff
--component-id ID (partial only) ID of the component to update
--binary-location PATH Custom path to language server binaries (overrides ~/.codeboarding/servers/)
--upload (full, remote only) Upload results to GeneratedOnBoardings repo
--enable-monitoring Enable run monitoring

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