// overview

Overview ¶

archi init scans the tree, reads the manifests and entry points, and asks one analyst pass to write down what it learned — cached under .archi/. Every design after that is grounded: Markdown briefings with Mermaid diagrams and file-by-file plans against your real modules. Approve a design and archi builds it — with diffs, versioned backups, and a verify-and-repair loop that runs your own toolchain.

Works with Ollama Cloud (default), Anthropic, or any OpenAI-compatible endpoint — OpenRouter, Groq, vLLM, llama.cpp.

// quick start

Quick start ¶

# install
go install github.com/devthedeveloper/archi@latest

# pick a provider (Ollama Cloud is the default)
export OLLAMA_API_KEY=…        # or ANTHROPIC_API_KEY / OPENAI_API_KEY

# learn a codebase, then design against it
cd my-service
archi init
archi design "make order processing idempotent"

In a terminal, design runs the full loop: a short interview, a streamed design, then approve & build, modify, or ask questions. Piped or with -no-interactive it prints pure Markdown, so it stays scriptable.

// features

Features ¶

// command reference

Command reference ¶

Ten commands. Flags shown are the ones you'll reach for; every command answers -h with the full set.

// integration: agents

MCP server ¶

archi serve speaks JSON-RPC 2.0 over stdin/stdout — the Model Context Protocol stdio transport — so agent clients call archi as tools. Every call is confined to the -root directory, writes are dry-run by default, and a dirty repo refuses real writes unless the caller says allow_dirty:true.

# Claude Code
claude mcp add archi -- archi serve -root "$(pwd)"

# Claude Desktop / Cursor — .mcp.json
{"mcpServers": {"archi": {"command": "archi", "args": ["serve"],
  "env": {"ARCHI_TIMEOUT": "10m"}}}}

stdout is 100% protocol JSON; progress and logging go to stderr. Provider keys come from the server's environment and never cross the wire.

// integration: teams

GitHub App ¶

archi-app — its own zero-dependency module under app/ — is a webhook service that runs the CLI in per-job workspace clones and posts results back to GitHub. Commenters need write access; every accepted command is acked with a 👀 reaction.

With auto_review: true in .github/archi.yml, every PR open and synchronize gets a review check automatically. Fork PRs are reviewed from the API diff — fork code is never checked out, and /archi build never runs on forks.

# .github/archi.yml — flat key: value only
provider: anthropic        # ollama | anthropic | openai
model: claude-fable-5
critic_model: claude-haiku-4-5
agents: full               # full | fast
auto_review: true
max_tokens: 12000

Deploying

One container (Dockerfile included) with git, both binaries, and a volume for the shared .archi cache. Required env: APP_ID, WEBHOOK_SECRET, PRIVATE_KEY_PATH or PRIVATE_KEY_BASE64. Tunables: WORKERS, QUEUE_SIZE, MAX_JOBS_PER_HOUR, JOB_TIMEOUT, CACHE_DIR, WORK_DIR, ARCHI_BIN. Jobs on one repo serialize under a per-repo lock; the cache is keyed by default-branch SHA, so an unchanged repo skips init entirely and a drifted one refreshes incrementally.

// configuration

Configuration ¶

Everything is environment variables — no config files to manage on the CLI side.

// documents

Documents archi writes ¶

.archi/
├── profile.md      the model's understanding
├── map.md          deterministic file map
├── config.json     provider, counts, settings
├── fingerprint     per-file drift hashes
├── designs/        every design, timestamped
│   └── 20260707-…-add-webhooks.md
├── backups/        originals from each build run
│   └── 20260707-142317/ + manifest.txt
├── memory/
│   └── decisions.md  ADR-ish team memory
└── runs/           agent traces, last 20

// releases

Releases ¶

• v1.8GitHub App — /archi comment commands, draft design PRs, auto-review check runs, per-repo job queue with SHA-keyed cache
• v1.7MCP server — archi serve exposes six tools over stdio for Claude Code, Claude Desktop, and Cursor
• v1.6Standing reviewers + memory — archi review CI contract, test-plan, doc, cross-session decision memory
• v1.5Build swarm — parallel packet builds with merge arbitration, verify-and-repair loop, rollback
• v1.4Design ensemble — explorer grounding briefs and the security/simplicity/grounding critic panel with revision rounds
• v1.3Agent runtime — orchestrator with bounded concurrency, run budgets, and traces (an invisible refactor)
• v1.2Production hardening — provider retries, OpenAI backend, secret redaction, versioned backups, fingerprint freshness, context budgeting
• v1.1Interactive design — interview, review loop, code generation, HTML export
• v1.0archi — init, design, status: an architect that knows your codebase