Who CodeBoarding is for#
Engineering leads reviewing AI-generated pull requests
When agents generate pull requests at a high rate, individual file-by-file review becomes a bottleneck. CodeBoarding draws the architecture change for each PR so leads can assess system impact, catch new cross-component dependencies, and return targeted context to the agent rather than approving changes they have not fully parsed.
Skip if:
If PRs are small, focused, and the team already holds the full system architecture in memory, the GitHub Action adds overhead without proportionate benefit. The tool's value scales with PR volume and codebase size.
Backend and frontend teams coordinating across subsystems
When backend and frontend codebases evolve in parallel, the component maps give both sides a shared architectural language. A backend change that modifies an interface a frontend PR depends on becomes visible before merge, rather than discovered in production.
Skip if:
Teams with a single unified codebase owned by one small team will see limited benefit from the cross-subsystem coordination angle. The architecture maps still add onboarding value, but the PR integration is most impactful across team boundaries.
Developers onboarding to an unfamiliar codebase
Running codeboarding full --local /path/to/repo on a new codebase generates an interactive architecture map and component descriptions without writing any documentation manually. Developers can explore how subsystems connect, navigate to source from any component, and build a system model before reading the code.
Skip if:
For repositories under a few thousand lines, reading the source directly is faster than running a full analysis. CodeBoarding's value scales with codebase complexity and the number of distinct components.
Teams generating architecture documentation from code
The --render flag produces Markdown with Mermaid diagrams, HTML, MDX, or reStructuredText for every component in the analysis. Documentation generated from codeboarding full --local /path --render mdx can go directly into a docs site, keeping architecture documentation in sync with the actual code without manual authoring.
Skip if:
If the team maintains hand-written architecture docs with intentional narrative and design constraints beyond what the code expresses, auto-generated docs may conflict with the manual record. The generated docs are accurate to the code but reflect structure, not intent.
The problem it solves#
Pull request diffs tell you what changed, not what the change means for the system. A 112-file diff with passing checks and 140 automated comments is technically reviewable, but the architectural decisions inside it are invisible to a reviewer scanning changed lines: which module now depends on which, which failure paths are new, and which subsystem is being restructured.
This problem compounds as AI coding agents produce pull requests faster than teams can read them. When agents write hundreds of files per day, the bottleneck shifts from generating code to understanding whether the generated code is safe to merge. The existing model of line-by-line review was not designed for this load, and reviewers end up either approving changes they do not fully understand or spending hours on diffs that should take minutes.
How it solves it#
Pull Request Architecture Diagrams
The GitHub Action draws a component-level change diagram for every pull request and posts it as a comment, showing which components changed (added, modified, or removed) and which dependencies are new. Reviewers see system impact in one Mermaid diagram before opening a single file.
Interactive Component Map in Browser and Editor
The web platform loads any analysis.json and renders the architecture as an interactive diagram: hover a component to trace its connections, click to see what flows in and out, and share a link with teammates. The same diagram loads inside VS Code, Cursor, and Windsurf via the extension.
Multi-Language Static Analysis via LSP
The analysis engine supports Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, and C# using language server protocol clients. Static analysis extracts symbols and call graph relationships from each language without requiring per-language configuration scripts.
Configurable LLM Provider
Any OpenAI-compatible gateway works as a provider: OpenAI, Azure Foundry, LM Studio, LiteLLM, OpenRouter. Anthropic, Google Gemini, AWS Bedrock, Vercel, and Ollama are also supported. Configure via ~/.codeboarding/config.toml or environment variables; shell env vars override the config file.
Documentation Rendering from Analysis
The CLI renders the architecture as Markdown with Mermaid diagrams, HTML, MDX, or reStructuredText. Running codeboarding full --local /path --render md generates an overview file and one file per expanded component, reconciled from a manifest on incremental runs. No web platform required.
Incremental and Partial Updates
After a full analysis, codeboarding incremental updates only changed components by diffing the working tree against the .codeboarding/analysis.json baseline. codeboarding partial updates a single component by ID. Both preserve the existing analysis, keeping repeated runs fast on large repositories.
Strengths and trade-offs#
Strengths
- MIT license, runs in your own GitHub ActionsThe analysis engine and CLI are MIT licensed. Source code is sent only to the model provider you configure, not to CodeBoarding's servers. Teams can run the full stack with a self-hosted Ollama instance and keep every artifact on-premises, with no dependency on the managed web platform for analysis results.
- Nine languages via a single installOne pipx install covers static analysis for Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, and C#. Language server binaries download to ~/.codeboarding/servers/ on first setup, shared across all projects. Node.js is bundled automatically if not present, removing a common setup blocker.
- Files are read only when you open themThe GitHub Action runs the analysis in your own Actions environment. Files are read only when you open them in the viewer; excerpts go to the model provider you configure. For teams that require data to stay in their own infrastructure, this is a firm boundary rather than a policy claim.
- Free CLI tier with no analysis meteringRunning the CLI locally against any repository carries no usage limit. The managed web platform's free tier adds metered analyses (diagrams three levels deep, no credit card required). Pro at $9.99/month adds unmetered analyses, ten-level depth, and health monitoring for teams that want the web features.
Trade-offs
- -Requires Python 3.12 and an LLM providerThe engine requires Python 3.12 specifically, not any 3.x version. An LLM provider must be configured before the analysis can describe components; there is no offline or no-model mode. Teams routing through a local Ollama instance avoid external API costs, but must run and maintain that service.
- -LSP setup adds install time and disk spaceLanguage server binaries for all supported languages download to ~/.codeboarding/servers/ on first run via codeboarding-setup. If Node.js is not installed, setup downloads a pinned Node.js runtime automatically, adding several hundred MB and a few minutes to the initial setup. Subsequent runs use the cached binaries.
- -Incremental analysis requires an existing baselineThe incremental command fails fast with 'run a full analysis first' if no .codeboarding/analysis.json exists in the output directory. Without committing .codeboarding/ to the repo, fresh checkouts always require a full re-analysis. Full analysis time scales with repository size and the model provider's response latency.
CodeBoarding vs alternatives#
CodeBoarding vs Sourcegraph
CodeBoarding and Sourcegraph both help engineering teams navigate large codebases, but they target different moments in the workflow. Sourcegraph focuses on code search and navigation across repositories at scale; CodeBoarding focuses on the pull request review moment, generating architecture change diagrams per PR.
| Feature | CodeBoarding | Sourcegraph |
|---|---|---|
| License | MIT (engine/CLI) | Apache 2.0 core / proprietary enterprise features |
| Self-hosting | Yes, runs in your GitHub Actions | Yes, requires infrastructure setup |
| Primary use case | PR architecture review | Code search and navigation |
| LLM integration | Any provider you configure | Cody AI (separate paid add-on) |
CodeBoarding is the better choice when the core need is understanding the system impact of individual pull requests, especially at high PR volume from AI coding agents. Sourcegraph is the better choice when the primary need is fast search across multiple repositories or when Cody AI's code assistant features are the priority.
CodeBoarding vs Swimm
Swimm is a code documentation tool that ties human-authored content to specific code locations, with PR-time alerts when the underlying code changes. CodeBoarding generates architecture documentation automatically from the code itself, without requiring authors to write and maintain it.
| Feature | CodeBoarding | Swimm |
|---|---|---|
| License | MIT (engine/CLI) | Proprietary |
| Self-hosting | Yes | No |
| Documentation approach | Auto-generated from code analysis | Human-authored, code-coupled |
| PR integration | Architecture change diagram per PR | Doc health alerts per PR |
CodeBoarding is the better fit when teams want generated architecture maps and PR diagrams without maintaining documentation manually. Swimm is the better fit when the goal is human-authored narrative documentation tied to specific code locations, particularly for onboarding flows where explanatory prose matters more than a generated component map.
Quick start#
Install via pipx for an isolated CLI environment, then run setup to download language server binaries.
```bash
pipx install codeboarding --python python3.12
codeboarding-setup
codeboarding full --local /path/to/repo
```What it's built on#
- Languages
- GoPythonTypeScript
- Frameworks
- FastAPI
- Infrastructure
- Docker
FAQ#
Is CodeBoarding free to use?
The MIT-licensed CLI and analysis engine are free with no usage limits when run locally. The managed web platform has a free tier with metered analyses and diagrams up to three levels deep, no credit card required. Pro is $9.99/month for unmetered analyses, ten-level depth, and health monitoring.
Does CodeBoarding send my source code to its servers?
No. The analysis runs in your own GitHub Actions environment and source files are read only when you open them in the viewer. Code excerpts go only to the model provider you configure. If you configure Ollama as the provider, no source code leaves your network.
Which programming languages does CodeBoarding support?
Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, and C# are supported via language server protocol clients. Node.js is required for the Python, TypeScript, JavaScript, and PHP language servers. If Node.js is not already present, setup downloads a pinned runtime automatically.
Which LLM providers can I use with CodeBoarding?
CodeBoarding works with any OpenAI-compatible gateway (OpenAI, Azure Foundry, LM Studio, LiteLLM, OpenRouter, Requesty), plus Anthropic, Google Gemini, AWS Bedrock, Vercel, and Ollama for local models. Configure in ~/.codeboarding/config.toml or via environment variables; shell variables override the config file.
Can I use CodeBoarding without a GitHub account?
Yes. The CLI runs fully locally: codeboarding full --local /path/to/repo analyzes any local repository without a GitHub account. The resulting analysis.json loads in the web platform via the Switch source to File picker, with all parsing done in the browser. The GitHub Action and PR review features require GitHub.
Similar open-source tools#
FckSignups
Open-source tools that work instantly, no signup required
Herdr
Agent runtime that keeps terminals alive across machines
Dyad
Local, open-source AI app builder with your own API keys
Cloudflare Os
Open source AI workspace with sandboxed apps and Gatekeeper security
Effect
Typed errors, DI, and concurrency for TypeScript
Firebase Ios Sdk
Open source Apple SDK for Firebase auth, data, push and crashes