Skip to main content

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

This 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-project
archbyte run

The 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-demo
cd microservices-demo && archbyte run --deep

For 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.

PlatformBinary
macOS, Apple Siliconarchbyte-darwin-arm64
macOS, Intelarchbyte-darwin-x64
Linux x64archbyte-linux-x64
Windows x64archbyte-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 archbyte

The same files, with release notes, are on GitHub releases.

Choosing a model

Run archbyte init at any time to choose again.

OptionWhat you needNotes
Claude Code (recommended)claude installed and signed inUses Sonnet for the scan and Opus for review agents, always the newest of each.
Codexcodex installed and signed inUses the model set in ~/.codex/config.toml unless you pick one.
Anthropic APIANTHROPIC_API_KEY or a pasted keyDefault: Claude Sonnet 5.5 for the scan, Claude Opus 5.5 for review agents.
OpenAI APIOPENAI_API_KEY or a pasted keyDefault: GPT-6.1 Sol and GPT-6 Astra. Works with Azure OpenAI via OPENAI_BASE_URL.
Google Gemini APIGEMINI_API_KEY or a pasted keyDefault: 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-5

To go back to the recommended pair:

archbyte config set model default

If 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 max

The 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 codex
archbyte doctor

Which 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-sol

That 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

CommandWhat it does
archbyte runScan, then open the diagram
archbyte analyzeScan only (for scripts and CI)
archbyte serveOpen the diagram from the last scan

A scan has two parts:

  1. 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.
  2. 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:6379 where redis-cart runs 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-project

Without a model

archbyte run --static

This 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).
  • Delete removes it from the view.
  • Cmd/Ctrl+Z undoes, Cmd/Ctrl+Shift+Z redoes.
  • Cmd/Ctrl+S saves positions.
  • Esc closes 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:

AgentLooks for
Security auditInjection, auth gaps, secret exposure, unsafe defaults
ComplianceData handling against common frameworks (GDPR, SOC 2 and similar)
PerformanceBottlenecks, N+1 patterns, missing caching, scaling limits
Dependency riskOutdated, unmaintained or risky packages
API contractsRoutes vs specs and clients, missing or undocumented endpoints
DriftDocs 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 agents
archbyte agents disable compliance api-contracts
archbyte agents enable all
archbyte run --agents security,drift

Names: 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 generate

Your 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: error

In custom rules, from and to are layer:<name>, type:<name> or a component id.

Export

CommandOutput
archbyte exportMermaid to stdout
archbyte export --format markdown -o docs/architecture.mdMarkdown
archbyte export --format plantumlPlantUML
archbyte export --format dot | dot -Tsvg > arch.svgDOT, drawn as SVG
archbyte export --format html -o architecture.htmlOne 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 mcp

Codex

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 update downloads 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: .env files, private keys, .npmrc, .netrc and similar secrets files. Templates such as .env.example are 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.md is 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's archbyte.yaml can only pick a provider you have already set up, and the scan says when settings come from that file.
  • Exclude anything else with a .archbyteignore file in the project root (.gitignore syntax), or turn data off in archbyte.yaml, as shown below.
  • archbyte run --debug prints exactly what was collected and sent.
  • The diagram server listens on 127.0.0.1 only.
privacy:
  sendCodeSamples: false
  sendDocs: false
  redact: true     # hash file paths and names before sending

Commands and flags

CommandWhat it does
archbyte runScan and open the diagram
archbyte analyzeScan only
archbyte serveOpen the diagram from the last scan
archbyte generateRedraw after editing archbyte.yaml
archbyte statsHealth metrics and rule checks
archbyte exportExport to other formats
archbyte initChoose provider and model
archbyte doctorCheck the setup with one test call
archbyte agentsList agents; enable or disable review agents
archbyte configShow or change settings
archbyte mcpStart the MCP server
archbyte updateUpdate to the latest version
archbyte versionVersion 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).

CommandWhat it does
archbyte config showShow the current settings
archbyte config set provider codexOne of claude-sdk, codex, anthropic, openai, google
archbyte config set model gpt-6-astraSet the model
archbyte config set api-key sk-...Set the API key

Environment variables

VariableEffect
ARCHBYTE_PROVIDERProvider for this run
ARCHBYTE_MODELModel for this run
ARCHBYTE_API_KEYAPI key for this run
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEYPicked up automatically
OPENAI_BASE_URLAzure 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).