ArchByte / User guide
ArchByte user guide.
ArchByte reads a codebase with AI agents and draws its architecture as an interactive diagram: the services, apps and libraries it is made of, what talks to what, the databases and outside services it depends on, and the main request flows. It runs on your machine, it is free, and there is no account.
This guide covers everything you can do with it. If you only read one section, read Quick start.
Quick start
1. Install
On macOS and Linux x64:
curl -fsSL https://diabhey.com/tools/archbyte/i | bashThis checks the download's SHA-256 checksum and puts a single archbyte binary in /usr/local/bin (or ~/.local/bin if that is not writable). Nothing else is installed. Update later with archbyte update.
On Windows, download archbyte-windows-x64.exe from Direct download below and put it on your PATH.
2. Have a model ready
The easiest is a coding agent you already use: Claude Code or Codex, installed and signed in. ArchByte uses its login, so you need no API key. An Anthropic, OpenAI or Google Gemini API key also works.
3. Run it
From your project folder:
cd my-projectarchbyte runThe first time, ArchByte asks which model to use and checks that it answers. Then it scans the project (usually under a minute for a small project, a few minutes for a large one) and opens the diagram in your browser at http://localhost:3847.
Not sure everything is set up? archbyte doctor checks in a few seconds and tells you what is missing.
Try it on a sample project
Before your own code, try a project built to exercise everything. Google's Online Boutique has 11 services in five languages talking over gRPC, a Redis cart and Kubernetes manifests:
git clone --depth 1 https://github.com/GoogleCloudPlatform/microservices-democd microservices-demo && archbyte run --deepFor the security agent specifically, OWASP Juice Shop is deliberately vulnerable, so you can judge the findings.
Direct download
Each release ships these binaries. The links always point at the latest version.
| Platform | Binary |
|---|---|
| macOS, Apple Silicon | archbyte-darwin-arm64 |
| macOS, Intel | archbyte-darwin-x64 |
| Linux x64 | archbyte-linux-x64 |
| Windows x64 | archbyte-windows-x64.exe |
Checksums for a version live at /tools/archbyte/downloads/checksums/v<version>. For example, on Apple Silicon:
curl -fsSL https://diabhey.com/tools/archbyte/downloads/latest/archbyte-darwin-arm64 -o archbyte && chmod +x archbyteThe same files, with release notes, are on GitHub releases.
Choosing a model
Run archbyte init at any time to choose again.
| Option | What you need | Notes |
|---|---|---|
| Claude Code (recommended) | claude installed and signed in | Uses Sonnet for the scan and Opus for review agents, always the newest of each. |
| Codex | codex installed and signed in | Uses the model set in ~/.codex/config.toml unless you pick one. |
| Anthropic API | ANTHROPIC_API_KEY or a pasted key | Default: Claude Sonnet 5.5 for the scan, Claude Opus 5.5 for review agents. |
| OpenAI API | OPENAI_API_KEY or a pasted key | Default: GPT-6.1 Sol and GPT-6 Astra. Works with Azure OpenAI via OPENAI_BASE_URL. |
| Google Gemini API | GEMINI_API_KEY or a pasted key | Default: Gemini 3.8 Flash and Gemini 4 Carbon. |
With an API key, archbyte init asks the provider which models your key can use, so new models appear without updating ArchByte. You can also type any model name. To use one model for everything:
archbyte config set model claude-opus-5-5To go back to the recommended pair:
archbyte config set model defaultIf you set nothing at all, ArchByte uses Claude Code if it is installed, then Codex, then whichever API key it finds in your environment.
Models and effort per project
Put a model: section at the top of the project's .archbyte/archbyte.yaml. It is kept on re-scan.
model:
provider: codex # claude-sdk, codex, anthropic, openai or google
scan: gpt-5.6-sol # model for the five scan agents
review: gpt-5.6-sol # model for the --deep review agents
effort: medium # minimal, low, medium, high, xhigh or maxThe same settings work globally, per provider: archbyte config set scan-model <name>, review-model <name> and effort <level>. For one run: archbyte run --model <name> --effort high. Flags and ARCHBYTE_* variables win, then the project file, then your global settings. Codex runs at medium unless you set an effort; Gemini ignores effort.
Switching to Codex
archbyte config set provider codexarchbyte doctorWhich Codex models can I use? That depends on how Codex is signed in, not on ArchByte. With a ChatGPT login (the usual one) you get only the models your plan offers in Codex; archbyte init (choose Codex) and a failing archbyte doctor list them, read from Codex's own list. For example, Sol on a ChatGPT plan may be gpt-5.6-sol while gpt-6.1-sol is API only. With an API key login (codex login --with-api-key) or the OpenAI API provider, any model your API account has works. "Requires a newer version of Codex" means the model exists for you but Codex is too old. Update it with npm install -g @openai/codex@latest.
archbyte config set model gpt-5.6-solThat sets the model for ArchByte only; change the model line in ~/.codex/config.toml to make it your Codex default everywhere. archbyte config set provider claude-sdk switches back to Claude Code; each provider keeps its own model. ArchByte runs Codex at medium effort unless you set one.
Cost
A scan makes five model calls (three in parallel, then two more). With Claude Code or Codex it counts against your plan like any other use. With an API key, a scan of a medium project typically uses tens of thousands of input tokens. archbyte run --static uses no model at all.
Scanning a project
| Command | What it does |
|---|---|
archbyte run | Scan, then open the diagram |
archbyte analyze | Scan only (for scripts and CI) |
archbyte serve | Open the diagram from the last scan |
A scan has two parts:
- Static scan (no model). ArchByte walks the file tree, package manifests, Dockerfiles, Compose and Kubernetes files (wherever they are), CI configs, env var names and docs. From Compose and Kubernetes it also keeps the addresses services are configured with, such as
CART_SERVICE_ADDR=cartservice:7070, with any passwords removed. In a project of services in different languages, that is how they find each other. - Agent pipeline. Three agents work in parallel (components, service descriptions, flows), then a connection mapper links components using evidence from the code and those addresses, and a validator removes connections it cannot support. A service configured with the address of a database container (
REDIS_ADDR=redis-cart:6379whereredis-cartruns Redis) gets that database and connection without a model guess.
Results go in .archbyte/ inside your project. Add it to .gitignore, or commit archbyte.yaml if you want the architecture reviewed like code.
Re-scans are incremental
In a git repository, ArchByte only re-reads the parts of the project that changed since the last scan, and skips the scan entirely when nothing relevant changed. After 20 commits it does a full scan. Use --force to always do a full scan.
Scanning another folder
archbyte run --dir ../other-projectWithout a model
archbyte run --staticThis draws a rough diagram from the static scan alone. It is free and fast but finds far less (often a handful of components where the agents find dozens).
The diagram
The diagram updates live. Leave it open while you work and it redraws after each scan.
- Layers. Rows from top to bottom: presentation (UIs), application (services, workers, libraries), data (databases, caches, queues), external (third-party APIs). Long layers wrap onto several rows.
- Click a component for its description, tech stack, source path and connections, and a deeper look at its internals.
- Layout re-arranges the diagram (by layer, left to right along the connections, one row, one column or a grid) and shows or hides whole layers.
- Flows plays a data flow step by step, for example "user signs up".
- Audit checks the diagram against your architecture rules.
- Review shows the results of the review agents.
- Sessions lists the Claude Code sessions in this project, so you can see which parts of the architecture an agent changed.
- Stats: counts, hubs (components with many connections) and orphans.
- Export: PNG, SVG, Mermaid, PlantUML, DOT, Markdown, JSON or a standalone HTML page.
Drag components to rearrange them. Positions you set by hand are kept on the next scan.
Keyboard
- Arrow keys move the selected component (Shift for bigger steps).
Deleteremoves it from the view.Cmd/Ctrl+Zundoes,Cmd/Ctrl+Shift+Zredoes.Cmd/Ctrl+Ssaves positions.Esccloses panels and stops a playing flow.
Review agents (--deep)
archbyte run --deep--deep adds six agents that read the code with read-only tools and report findings in the Review panel:
| Agent | Looks for |
|---|---|
| Security audit | Injection, auth gaps, secret exposure, unsafe defaults |
| Compliance | Data handling against common frameworks (GDPR, SOC 2 and similar) |
| Performance | Bottlenecks, N+1 patterns, missing caching, scaling limits |
| Dependency risk | Outdated, unmaintained or risky packages |
| API contracts | Routes vs specs and clients, missing or undocumented endpoints |
| Drift | Docs that no longer match the code, layering violations, dead code |
Choose which agents run
archbyte agents lists every agent and whether it runs. The five scan agents always run, because they draw the diagram. Review agents can be turned off per project (saved as review-agents: in archbyte.yaml) or picked for one run:
archbyte agentsarchbyte agents disable compliance api-contractsarchbyte agents enable allarchbyte run --agents security,driftNames: security, compliance, performance, dependencies, api-contracts, drift.
They run three at a time and add a few minutes to a scan. Treat their output as a reviewer's notes, not a verdict. Check each finding before acting on it.
Editing the result
.archbyte/archbyte.yaml is the architecture in plain YAML: components, databases, external services, connections, flows and environments. Edit it by hand to rename, merge or add things, then redraw:
archbyte generateYour edits are kept on the next scan. Only components whose code changed are updated.
Architecture rules
Rules live in archbyte.yaml. The Audit panel checks the diagram against them and lets you change them. archbyte stats reports the built-in ones.
rules:
no-layer-bypass: warn # e.g. a UI talking straight to a database
no-circular-deps: warn
no-orphans: off
max-connections:
level: warn
threshold: 8
custom:
- name: "No direct DB access from UI"
from: "layer:presentation"
to: "type:database"
level: errorIn custom rules, from and to are layer:<name>, type:<name> or a component id.
Export
| Command | Output |
|---|---|
archbyte export | Mermaid to stdout |
archbyte export --format markdown -o docs/architecture.md | Markdown |
archbyte export --format plantuml | PlantUML |
archbyte export --format dot | dot -Tsvg > arch.svg | DOT, drawn as SVG |
archbyte export --format html -o architecture.html | One self-contained page |
The Mermaid and Markdown exports render directly in GitHub READMEs and pull requests.
Use from coding agents (MCP)
ArchByte includes an MCP server so Claude Code, Codex, Cursor and other agents can scan a project and read its architecture.
Claude Code
claude mcp add archbyte -- archbyte mcpCodex
Add this to ~/.codex/config.toml:
[mcp_servers.archbyte]
command = "archbyte"
args = ["mcp"]What agents get
Tools: archbyte_analyze, archbyte_export, archbyte_stats, archbyte_validate. Resources: the components, connections and flows of the last scan.
A useful prompt: "Use archbyte to scan this repo, then explain how a request reaches the database."
Privacy
- ArchByte talks to one place, the model provider you chose. There is no ArchByte server, account, telemetry or licence check.
archbyte updatedownloads new versions from diabhey.com and installs one only if its checksums carry a valid signature from the ArchByte release key built into your current version, so a tampered download server cannot push an update. - What the model sees: the file tree, excerpts of key files (entry points, routes, configs), package manifests, infra files, env var names (never values) and docs.
- Never read:
.envfiles, private keys,.npmrc,.netrcand similar secrets files. Templates such as.env.exampleare read. - Coding agents run read-only and isolated from the project. Claude Code runs from an empty temporary folder in restricted mode: no tools that run commands, no settings files (so a repository's own hooks never run), no MCP servers, and the project's
CLAUDE.mdis not loaded. Calls that explore the code get only Read, Glob and Grep, confined to the project, with secrets files denied. On macOS, Codex runs inside ArchByte's own system sandbox. It can read only the project (secrets files denied) or, for calls that need no files, nothing of yours at all. It can write only to a private temporary folder and its own logs, and its config and login stay read-only. On Linux and Windows Codex uses its built-in read-only sandbox, which can read files outside the project, so prefer Claude Code or an API key there for code you do not trust. - A project's settings cannot redirect your code. A
model:section in a repository'sarchbyte.yamlcan only pick a provider you have already set up, and the scan says when settings come from that file. - Exclude anything else with a
.archbyteignorefile in the project root (.gitignoresyntax), or turn data off inarchbyte.yaml, as shown below. archbyte run --debugprints exactly what was collected and sent.- The diagram server listens on
127.0.0.1only.
privacy:
sendCodeSamples: false
sendDocs: false
redact: true # hash file paths and names before sendingCommands and flags
| Command | What it does |
|---|---|
archbyte run | Scan and open the diagram |
archbyte analyze | Scan only |
archbyte serve | Open the diagram from the last scan |
archbyte generate | Redraw after editing archbyte.yaml |
archbyte stats | Health metrics and rule checks |
archbyte export | Export to other formats |
archbyte init | Choose provider and model |
archbyte doctor | Check the setup with one test call |
archbyte agents | List agents; enable or disable review agents |
archbyte config | Show or change settings |
archbyte mcp | Start the MCP server |
archbyte update | Update to the latest version |
archbyte version | Version and environment |
Flags
For run and analyze: --dir <path>, --deep, --agents <list>, --model <name>, --effort <level>, --static, --force, --provider <name>, --api-key <key>, --debug, --dry-run, --verbose.
For run and serve: --port <n>, --no-open.
Every command accepts --json (machine-readable output) and --quiet.
Settings and environment variables
Settings are in ~/.archbyte/config.json (archbyte config path prints it).
| Command | What it does |
|---|---|
archbyte config show | Show the current settings |
archbyte config set provider codex | One of claude-sdk, codex, anthropic, openai, google |
archbyte config set model gpt-6-astra | Set the model |
archbyte config set api-key sk-... | Set the API key |
Environment variables
| Variable | Effect |
|---|---|
ARCHBYTE_PROVIDER | Provider for this run |
ARCHBYTE_MODEL | Model for this run |
ARCHBYTE_API_KEY | API key for this run |
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY | Picked up automatically |
OPENAI_BASE_URL | Azure OpenAI or another compatible endpoint |
Troubleshooting
Start with archbyte doctor. It names the provider in use and makes one test call.
Not logged in (Claude Code)
Run claude once and sign in.
requires a newer version of Codex
Update Codex: npm install -g @openai/codex@latest.
model is not supported when using Codex with a ChatGPT account
Pick a model your plan includes: archbyte config set model <name>, or change ~/.codex/config.toml.
How do I stop a scan or the diagram?
Press Ctrl+C during a scan, or q (or Ctrl+C) while the diagram is open. If it runs in another terminal or will not stop: pkill -f archbyte. A scan you cut off can leave model calls running; stop them with pkill -f "claude -p" or pkill -f "codex exec".
No model provider configured
Install Claude Code or Codex, or set an API key, then run archbyte init.
No changes detected since last scan
Nothing relevant changed. Use --force to scan anyway.
Port 3847 is already in use
Pick another port when asked, or run archbyte run --port 4000. To free the port from an old run: lsof -ti:3847 | xargs kill.
A scan seems stuck
It is usually waiting on a slow model call; the progress line shows which agent and for how long. Run ArchByte inside one repository, not a folder of many repositories or worktrees. With Codex, lower the effort: archbyte config set effort low. Stop it with Ctrl+C.
The scan fell back to "static"
The model call failed. The message above it says why. Run archbyte doctor.
Diagram looks wrong
Edit .archbyte/archbyte.yaml, then run archbyte generate.
Upgrading from 0.8 or earlier
ArchByte used to live at archbyte.heartbyte.io and needed an account. From 0.9.0 it is free with no account, and the old install and update servers are being retired, so archbyte update in 0.8.2 or earlier will stop working. Reinstall once with the install command above. archbyte update works after that.
You can delete ~/.archbyte/credentials.json and ~/.archbyte/tier-cache.json. Your provider settings in ~/.archbyte/config.json carry over.
Found a bug? Open an issue on GitHub. For other questions, get in touch. ArchByte is free for personal and commercial use (licence).