CodeBoarding: architecture diagrams for codebases, generated by static analysis plus an LLM

What CodeBoarding produces and who the output is for

The README frames the project around a specific fear: seeing what an AI agent is building before it breaks. That is narrower than a general documentation generator. The stated use cases are keeping architecture visible while agents code, reviewing AI-generated changes with system context, understanding large repositories faster, and sharing one visual model across local workflows, IDEs, pull requests and docs. The intended reader is a developer who has inherited or generated more code than they can hold in their head.

The artifact list is concrete. CodeBoarding generates high-level system architecture diagrams, deeper component diagrams for important subsystems, Markdown documentation in a .codeboarding/ directory, Mermaid output that embeds in docs and PRs, and incremental updates when only part of the codebase changes. Because the output is Mermaid and Markdown rather than a proprietary binary, it can be reviewed in a diff. That matters more than it sounds: a diagram that lives in a text file can be argued about in a pull request, and a diagram locked in a web canvas cannot.

The project also ships an Open VSX extension and a VS Code extension, plus a GitHub Action listed on the Marketplace. The README's own repository contains a .codeboarding/ directory with per-component Markdown files, so the project runs its tool on itself.

Static analysis, an LLM agent, and an incremental cache

The architecture diagram in the README names six pieces: an application orchestrator and repository manager, an LLM agent core, a static code analyzer, an agent tooling interface, an incremental analysis engine, and a documentation and diagram generator. The edges between them describe the data flow. The orchestrator starts the workflow and hands project context to the LLM agent. It also drives the incremental engine, which requests static analysis only for new or changed code segments and caches the results. The agent does not read the repository directly; it calls tools through the agent tooling interface, and those tools query the static analyzer for detailed code insights. The agent's structured findings are then passed to the documentation and diagram generator.

That split is the interesting design decision. Tree-sitter grammars supply the syntax layer, and pyproject.toml pins grammars for Python, JavaScript, TypeScript, Java, Go, Rust, PHP and C#. The LLM layer sits above the parse tree and decides what constitutes a component and how components relate. Static analysis alone gives you call graphs and imports; it does not tell you that a module is a subsystem worth drawing. The LLM supplies that judgement, and the static analyzer keeps it grounded in real symbols.

The cost of that choice is that the pipeline is not purely deterministic. Two runs against the same commit can, in principle, produce different diagrams, because a language model is in the loop. The README does not document a seeded or deterministic mode. The incremental engine softens the practical cost by scoping re-analysis to changed segments, but it does not remove the model dependency.

Installing CodeBoarding and running it on a repository

The packaged CLI requires Python 3.12 or 3.13. The recommended install path is pipx, which keeps the CLI in an isolated environment, and the README pins the interpreter explicitly:

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

The setup command runs once and configures the tool; the second command points it at a local checkout. After a successful run, the README states that output is written to /path/to/repo/.codeboarding/, and that the CLI prints a reminder about the web platform after every successful run. If you prefer pip, the README insists on a virtual environment rather than the global Python, and the package index is not the default one:

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

Running from source follows a different path. The README gives uv as the environment tool, then a Python install script, then the entry point:

uv sync --frozen
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python install.py
python main.py full --local /path/to/repo

To look at the result interactively, the README says to open the web platform at app.codeboarding.org and drop in the generated analysis.json. It states that the file stays in the browser and nothing is uploaded. The CLI prints that reminder after every successful run, which suggests the project expects the browser step to be part of the normal workflow rather than an optional extra.

The LLM dependency is the real constraint

The dependency list in pyproject.toml includes langchain, langgraph, and provider packages for Anthropic, AWS, Cerebras, Google GenAI, Ollama and OpenAI. That is a wide provider surface, and Ollama means a local model is at least theoretically supported. But the README does not explain how to choose a provider, which environment variables to set, or what the setup command prompts for. A reader who installs the CLI and runs codeboarding-setup is relying on the interactive flow to surface those choices, and the README does not describe what happens if no provider is configured.

The second constraint is scope. The README lists eight languages through tree-sitter grammars, but a grammar is not the same as full semantic understanding. Languages with dynamic dispatch, heavy metaprogramming, or generated code will produce a weaker static layer, and the LLM is then reasoning over a thinner signal. Nothing in the README promises coverage guarantees per language, and there is no accuracy metric published. Treat the diagrams as a reading aid, not as an authoritative dependency specification.

The third constraint is that the project classifies itself as Development Status :: 4 - Beta. Version 0.14.2 in pyproject.toml, with releases v0.14.1 on 2026-09-08, v0.14.0 on 2026-09-06 and v0.13.2 on 2026-09-01, indicates a fast release cadence. Fast cadence in a beta means the output format and CLI surface can move. If you wire the CLI into CI, pin the version.

CodeBoarding compared with GitDiagram and hand-written Mermaid

The related searches around this project include GitDiagram alternative, which is the comparison people actually want. GitDiagram also turns a repository into a diagram, and the difference in approach is where the analysis happens. A GitDiagram-style tool leans on the model to read the repository and emit a diagram in one pass. CodeBoarding inserts a static analysis layer between the model and the code, exposes that layer to the model through tools, and caches per-segment results so a second run only reprocesses what changed. The output is also split across a .codeboarding/ directory of component Markdown files plus Mermaid, rather than a single diagram image.

That architecture costs more moving parts: tree-sitter grammars per language, a tool interface, an incremental engine, and a LangGraph-orchestrated agent. It buys two things a single-pass generator does not have. First, the model's claims can be traced back to parsed symbols. Second, reruns after a small commit are cheaper because the incremental engine scopes the work.

The other alternative is writing Mermaid by hand. That is deterministic, reviewable, and free of API keys. It also decays: nobody updates the hand-drawn diagram after the third sprint. CodeBoarding's bet is that a generated diagram with a cache is more likely to stay current than a hand-maintained one. Whether that bet pays off depends on how often you rerun it, which is a workflow question the tool cannot answer for you.

Licence, telemetry and upgrade cost

CodeBoarding is MIT licensed, both in the repository LICENSE file and in the license field of pyproject.toml. MIT is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and permission notice are retained. That is the extent of what the repository states; it is not legal advice, and if you redistribute the CLI inside a product you should read the full licence text rather than this summary.

The repository contains a TELEMETRY.md file and a telemetry/ directory, and posthog appears in the dependency list. The README does not describe what is collected or how to turn it off; the file named TELEMETRY.md is where that would be documented. If you plan to run the CLI inside a corporate network or against proprietary code, read that file before the first run rather than after. The x-pxid tracking pixels in the README's own badge links are a separate thing from the CLI, but they show the project tracks usage at the documentation level too.

Upgrade cost is shaped by the beta status and the release pace. Three releases landed in the first eight days of September 2026. The CLI surface shown in the README (codeboarding full --local) is small, so breakage is more likely in the generated output format than in the command line. If you check .codeboarding/ into version control, expect diffs on every upgrade.

Editorial conclusion

Adopt CodeBoarding if you want a Mermaid architecture map and component-level Markdown for a repository you are onboarding onto, or if you want a visual model to attach to pull requests. Skip it if you need a deterministic, offline, byte-for-byte reproducible artifact, since the LLM agent is part of the pipeline and the README does not document a no-LLM mode. Before committing to it, run codeboarding full --local against one real repository and read the generated .codeboarding/ tree, then check whether the web platform's analysis.json handling matches your data policy.

Frequently asked questions

Official sources

1. CodeBoarding/CodeBoarding on GitHub
2. License: MIT
3. Project website
4. README
5. Releases