Archbyte

AI-powered architecture visualization for your codebase. Analyzes code, generates interactive diagrams, enforces architectural fitness rules, and monitors for drift — all from Claude Code.

Quick Start

# Run directly — no install required
npx archbyte run

On first run, ArchByte walks you through sign-in and provider setup interactively. Your API keys stay on your machine — ArchByte never stores or transmits your provider credentials.

Manual setup

Prefer to configure each step separately:

npx archbyte login          # Sign in or create a free account
npx archbyte init           # Configure your AI provider (BYOK)

Global install (optional)

If you prefer a persistent install:

npm install -g archbyte
archbyte run

Setup with Claude Code

Slash commands — installed globally so they work in any project:

mkdir -p ~/.claude/commands
cp commands/archbyte-*.md ~/.claude/commands/

Run /archbyte-help in Claude Code to see all commands.

Usage (Claude Code slash commands)

| Command | What it does | |---------|-------------| | /archbyte-analyze | Scans your codebase and generates .archbyte/analysis.json | | /archbyte-generate | Converts analysis into .archbyte/architecture.json with positioned nodes | | /archbyte-serve | Opens interactive diagram UI at http://localhost:3847 | | /archbyte-stats | Shows architecture health dashboard | | /archbyte-export | Exports diagram to Mermaid, Markdown, or other formats | | /archbyte-workflow | Runs composable multi-step architecture pipelines | | /archbyte-init | Initializes archbyte.yaml config for your project | | /archbyte-help | Shows this command reference |

Typical workflow

/archbyte-init        # one-time: create config
/archbyte-analyze     # AI scans your code
/archbyte-serve       # view the diagram

CLI Commands

archbyte login

Sign in or create a free account. Shows an interactive provider picker (GitHub, Google, Email & Password).

npx archbyte login              # interactive provider picker
npx archbyte login --github     # sign in with GitHub
npx archbyte login --google     # sign in with Google
npx archbyte login --email      # sign in with email and password
npx archbyte login --token JWT  # login with a pre-existing JWT token

Multiple accounts are supported. If already logged in, you'll be prompted to add a different account.

archbyte logout

Sign out of ArchByte.

npx archbyte logout              # logout active account
npx archbyte logout [email protected]  # logout specific account
npx archbyte logout --all        # logout all accounts

archbyte accounts

List and manage logged-in accounts.

npx archbyte accounts                    # list all accounts
npx archbyte accounts switch             # interactive account switcher
npx archbyte accounts switch [email protected] # switch to specific account

archbyte status

Show account status, tier, and usage.

npx archbyte status

archbyte init

Scaffold an archbyte.yaml config and .archbyte/ directory.

npx archbyte init
npx archbyte init --force    # overwrite existing

Why this matters: Without a config, every team member picks their own rules and thresholds. init gives your project a single source of truth for architecture governance from day one.

Example: You join a new monorepo and want to enforce "no direct DB calls from the frontend." Run npx archbyte init, edit the generated archbyte.yaml to add that custom rule, and commit it — now every contributor shares the same guardrails.

archbyte generate

Convert analysis JSON into an architecture diagram.

npx archbyte generate
npx archbyte generate --input path/to/analysis.json --output path/to/arch.json
npx archbyte generate --verbose

Merges with existing diagram to preserve user-adjusted node positions.

Why this matters: Raw analysis JSON is data — a positioned architecture diagram is understanding. Generate turns a flat list of components and dependencies into a spatial map you can actually reason about.

Example: After an AI analysis finds 40 components and 120 dependencies, npx archbyte generate lays them out by layer so you instantly see that your "AuthService" sits in the wrong tier. Re-running after code changes merges new nodes in without losing the positions you manually adjusted last sprint.

archbyte serve

Start the HTTP server with the interactive visualization UI.

npx archbyte serve                    # default port 3847
npx archbyte serve --port 8080
npx archbyte serve --diagram path/to/architecture.json

Features: real-time SSE updates, drag-and-drop nodes, environment filtering, flow animation, dependency highlighting, export to PNG/SVG.

Why this matters: Architecture diagrams on a wiki go stale the moment they're drawn. A live, interactive diagram that updates in real-time means you're always looking at the truth, not a six-month-old Confluence page.

Example: During an incident review, run npx archbyte serve and drag the failing service to the center. Click it to highlight all upstream dependencies — now the whole team can see which services are affected and trace the blast radius visually instead of grep-ing through YAML manifests.

archbyte stats

Architecture health dashboard.

npx archbyte stats
npx archbyte stats --diagram path/to/architecture.json

Shows: component counts, layer distribution, connection density, hub detection, orphan detection, layer violations.

Why this matters: "How healthy is our architecture?" is usually answered with gut feelings. Stats turns that into numbers you can track over time and discuss objectively in sprint retros.

Example: You run npx archbyte stats and discover your ApiGateway has 14 connections — more than double the threshold. That's a hub risk: if it goes down, 14 services are affected. You bring this to the team meeting with hard data instead of a hunch, and the team agrees to split it into domain-specific gateways.

archbyte export

Export to various formats.

npx archbyte export                              # mermaid to stdout
npx archbyte export --format plantuml
npx archbyte export --format dot                 # Graphviz
npx archbyte export --format markdown
npx archbyte export --format json
npx archbyte export --output docs/architecture.mmd

Why this matters: Your architecture diagram shouldn't be locked inside one tool. Export lets you embed it in PRs, design docs, ADRs, or any toolchain your team already uses.

Example: Before each release, you run npx archbyte export --format mermaid --output docs/architecture.mmd and commit it. GitHub renders the Mermaid diagram inline in your repo — anyone browsing the codebase sees an always-current architecture map without installing anything.

archbyte mcp

Start the MCP (Model Context Protocol) server for AI agent integration.

npx archbyte mcp                          # start MCP server on stdio

Exposes ArchByte tools (analyze, status, export, stats, validate) and resources to any MCP-compatible client (Claude Code, VS Code, etc.).

Why this matters: MCP lets AI agents call ArchByte tools directly without going through the CLI. This enables seamless integration where Claude Code can analyze your architecture, check stats, and export diagrams as part of a larger agentic workflow.

archbyte workflow

Composable multi-step architecture pipelines with dependency tracking and resume-on-failure. Inspired by Gastown's MEOW (Molecular Expression of Work) system.

npx archbyte workflow --list                  # list available workflows
npx archbyte workflow --run full-analysis     # run a workflow
npx archbyte workflow --show ci-check         # show step details
npx archbyte workflow --status                # show progress bars
npx archbyte workflow --create "my-pipeline"  # scaffold a custom workflow
npx archbyte workflow --reset                 # clear all state

Built-in workflows:

| Workflow | Steps | Description | |----------|-------|-------------| | full-analysis | generate -> validate -> stats -> export | Complete pipeline | | ci-check | validate (CI mode) | Lightweight CI gate | | drift-check | snapshot -> generate -> diff | Detect drift |

Custom workflows — YAML files in .archbyte/workflows/:

id: my-pipeline
name: "My Custom Pipeline"
description: "Custom architecture workflow"

steps:
  - id: generate
    name: "Generate Diagram"
    command: "archbyte generate"
    needs: []

  - id: validate
    name: "Validate"
    command: "archbyte validate --ci"
    needs: [generate]

  - id: export
    name: "Export"
    command: "archbyte export --format mermaid --output docs/arch.mmd"
    needs: [generate]

Workflows resume on failure — completed steps are skipped when you re-run. State persists in .archbyte/workflows/.state/.

Why this matters: Running generate, then validate, then stats, then export manually is tedious and error-prone. Workflows chain them into a single reproducible pipeline — and if step 3 fails, you re-run and it skips the already-completed steps instead of starting from scratch.

Example: You add a ci-check workflow to your GitHub Actions. On every PR, it runs npx archbyte workflow --run ci-check, which validates architecture rules in CI mode and exits non-zero on violations. No manual steps, no forgotten checks. For bigger releases, npx archbyte workflow --run full-analysis runs the entire generate-validate-stats-export pipeline in one command and produces a Mermaid diagram committed to docs/.

Global Flags

These flags work with any command:

| Flag | Description | |------|-------------| | --json | Output structured JSON instead of human-readable text | | --quiet | Suppress all non-essential output (spinners, progress bars) |

npx archbyte status --json          # machine-readable status
npx archbyte stats --json           # structured stats output
npx archbyte export --json          # JSON envelope around export
npx archbyte analyze --quiet        # suppress progress output

Keyboard Shortcuts (UI)

| Key | Action | |-----|--------| | Ctrl/Cmd + F | Search | | Ctrl/Cmd + S | Save positions | | Ctrl/Cmd + E | Export PNG | | Escape | Clear search / close panel | | Delete | Hide selected node |

Requirements

• Node.js >= 18 (for npx archbyte)
• Claude Code (for /archbyte-analyze slash commands)

License

MIT