Metadata-Version: 2.4
Name: codeboarding
Version: 0.15.3
Summary: Interactive Diagrams for Code
Author: CodeBoarding Team
License-Expression: MIT
Project-URL: Repository, https://github.com/CodeBoarding/CodeBoarding
Project-URL: Documentation, https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/overview.md
Keywords: code-understanding,code-visualization,code-analysis,diagrams,documentation,llm,static-analysis,mermaid,onboarding
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docker>=7.1
Requires-Dist: dotenv>=0.9
Requires-Dist: dulwich>=0.22
Requires-Dist: fastapi>=0.115
Requires-Dist: filelock>=3.12
Requires-Dist: gitpython>=3.1
Requires-Dist: google-api-core>=2.10
Requires-Dist: jsonpatch>=1.33
Requires-Dist: jsonschema>=4.25
Requires-Dist: langchain>=1.2
Requires-Dist: langchain-anthropic>=1.3
Requires-Dist: langchain-aws>=1.1
Requires-Dist: langchain-cerebras>=0.8
Requires-Dist: langchain-community>=0.4
Requires-Dist: langchain-core>=1.2
Requires-Dist: langchain-google-genai>=3.1
Requires-Dist: langchain-ollama>=1.0
Requires-Dist: langchain-openai>=1.1
Requires-Dist: langgraph>=1.0
Requires-Dist: markdown>=3.8
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: markitdown>=0.1
Requires-Dist: networkx>=3.4
Requires-Dist: nodeenv>=1.10.0
Requires-Dist: pathspec>=0.12
Requires-Dist: posthog>=3.7
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: regex>=2024.11
Requires-Dist: requests>=2.32
Requires-Dist: rich>=12.6
Requires-Dist: tqdm>=4.67
Requires-Dist: tree-sitter==0.25.2
Requires-Dist: tree-sitter-c-sharp==0.23.5
Requires-Dist: tree-sitter-go==0.25.0
Requires-Dist: tree-sitter-java==0.23.5
Requires-Dist: tree-sitter-javascript==0.25.0
Requires-Dist: tree-sitter-language-pack==1.21.0
Requires-Dist: tree-sitter-php==0.24.1
Requires-Dist: tree-sitter-python==0.25.0
Requires-Dist: tree-sitter-rust==0.24.2
Requires-Dist: tree-sitter-typescript==0.23.2
Requires-Dist: uvicorn>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=7.0; extra == "dev"
Requires-Dist: black>=25.9; extra == "dev"
Requires-Dist: mypy>=1.19; extra == "dev"
Requires-Dist: pre-commit>=3.8; extra == "dev"
Provides-Extra: all
Requires-Dist: codeboarding[dev]; extra == "all"
Requires-Dist: pylint>=3.3; extra == "all"
Requires-Dist: pyright>=1.1; extra == "all"
Requires-Dist: pyinstaller>=6.13; extra == "all"
Requires-Dist: memory-profiler>=0.61; extra == "all"
Dynamic: license-file

# CodeBoarding

[![Website](https://img.shields.io/badge/Site-CodeBoarding.org-5865F2?style=for-the-badge&logoColor=white)](https://codeboarding.org)
[![Web platform](https://img.shields.io/badge/Web%20platform-app.codeboarding.org-2563EB?style=for-the-badge&logoColor=white)](https://app.codeboarding.org)
[![Discord](https://img.shields.io/badge/Discord-Join%20Us-5865F2?style=for-the-badge&logoColor=white)](https://discord.gg/T5zHTJYFuy)
[![GitHub](https://img.shields.io/badge/GitHub-CodeBoarding-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/CodeBoarding/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 · Kotlin · Go · PHP

---

## Requirements

- **Python 3.12 or 3.13** — other versions are currently not supported.
- **Linux:** glibc 2.34 or newer (Ubuntu 22.04, Debian 12, RHEL 9 or later), for the Kotlin parser.

## Installation

The recommended way to install the CLI is with [pipx](https://pipx.pypa.io), which automatically creates an isolated environment:

```bash
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:

```bash
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.

Each analysis downloads the language servers its repository's languages need, on first use. To pre-install all of them (useful in CI or restricted environments):

```bash
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

```bash
# 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](https://app.codeboarding.org) and load the
generated `.codeboarding/analysis.json` — it is parsed in your browser, nothing is uploaded.

### Python API

```python
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:

```toml
# ~/.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
```

| Option | Description |
|---|---|
| `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
| `--render {md,html,mdx,rst}` | Render overview and component files from the local `analysis.json` for full, incremental, or partial commands |
| `--depth-cap INT` | Maximum allowed hierarchy depth for automatic expansion (default: 3), not a target. Components can still be expanded on demand. Configures `metadata.depth_cap`, not `metadata.depth_level` (the depth actually reached). No input alias is accepted. |
| `--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](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding)** — browse diagrams directly in your IDE
- **[GitHub Action](https://github.com/marketplace/actions/codeboarding-diagram-first-documentation)** — generate docs on every push
- **[MCP Server](https://github.com/CodeBoarding/CodeBoarding-MCP)** — serve concise architecture docs to AI coding assistants (Claude Code, Cursor, etc.)

---

## Links

- [Source code](https://github.com/CodeBoarding/CodeBoarding)
- [Example diagrams (800+ open-source projects)](https://github.com/CodeBoarding/GeneratedOnBoardings)
- [Architecture documentation](https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/overview.md)
- [Discord community](https://discord.gg/T5zHTJYFuy)
