Documentation
Archmantic turns any repo into a living, provenance-grounded architecture model — visual diagrams for humans, an MCP surface for agents.
What is Archmantic#
Point Archmantic at a repo and it reverse-engineers a single architecture model (the IR). Every diagram — C4-style context, components, sequence (Mermaid), an auto-detected BPMN business process, and an ERD of your data model (from Prisma, Drizzle, or SQL migrations), plus a detected API surface (REST/tRPC/ GraphQL) — is a projection of that one model. Every element is traceable to file:line with a confidence band, so it's verifiable, not plausible AI guesswork.
The same model answers your AI agent's questions over MCP, so the agent reads the model instead of whole files (~98% fewer tokens on this repo, by the built-in benchmark).
Install#
No install needed — run it straight from npm:
npx archmantic analyze
npx archmantic viewOr install the CLI globally:
npm install -g archmantic
amt analyze # short alias for "archmantic"Requires Node 24+. The core CLI is Apache-2.0 and dependency-light.
Quickstart#
From the root of any repo:
npx archmantic analyze # → .archmantic/model.json (the model)
npx archmantic view # → .archmantic/view.html (diagrams + trust report)
npx archmantic bench # token savings: MCP vs raw file readsanalyze runs cheapest-first: repo structure, then a static import graph (TypeScript compiler API), then structural capabilities and a process flow. Add --tier 2 for the optional LLM semantic pass (bring your own Anthropic key).
Connect a team#
Share one model across your team and agents. Generate a CLI token on the tokens page, add it to your repo's .env.local, then push:
# .env.local
ARCHMANTIC_TOKEN=am_xxx
npx archmantic push # upload the model to your org
npx archmantic pull # fetch the latest team modelEach push is stored per commit, so you get an architecture history and per-PR diffs. Your teammates and agents read the same model in this web app.
CLI reference#
| Command | What it does |
|---|---|
init [name] | Create an empty .archmantic/model.json |
analyze [--tier N] | Reverse-engineer the model. --tier 2 adds the LLM semantic pass (BYOK) |
update [--hook] | Incrementally re-analyze only what changed (git-diff driven). --hook prints a pre-commit hook |
view | Capability map, diagrams, and trust report → a self-contained view.html |
spec | Emit an agent-ready build spec (build-spec.md + .json) from the model |
knowledge | Refresh AGENTS.md agent-context file (managed block; auto on analyze/update) |
apply [--from f] | Merge a human BPMN canvas edit back into the model — the “edit” of edit-then-build |
handoff [--apply] | Run the build spec through Claude → a plan; --apply runs an autonomous agent that edits the repo and self-verifies |
drift [--check] | Compare the committed model vs. the code; --check exits 1 on drift (CI gate) |
diff [<ref>] | Architecture diff from a git ref → working tree; writes PR-comment-ready pr-diff.md |
log [-n N] | Architecture history: how the architecture changed per commit |
system [name] | Unified cross-service view across repos (declare links in .archmantic/config.json) |
push / pull | Sync the model to/from the Archmantic cloud (token or DATABASE_URL) |
usage [--sync] | MCP usage + token savings; --sync pushes the local log to the cloud /usage dashboard |
mcp | Start the MCP server exposing the model to AI agents (stdio) |
bench [--exact] | Token-savings benchmark; --exact uses the Anthropic token counter (BYOK) |
MCP for agents#
Expose the model to any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, …). First build the model once, then register the server with your agent — you don't run it by hand.
amt analyze # build .archmantic/model.json (once)Claude Code — register it from the project directory:
claude mcp add archmantic -- npx archmantic mcpClaude Desktop / Cursor — add it to the client's mcpServers config:
{
"mcpServers": {
"archmantic": {
"command": "npx",
"args": ["archmantic", "mcp"]
}
}
}It's a long-running stdio server. Your agent launches it on demand, talks to it over stdin/stdout, and shuts it down afterward — so it stays running while connected (that's by design, not a hung process). You normally never run archmantic mcp yourself; if you do, it prints a notice and waits — press Ctrl-C to stop.
Once connected, the agent queries components, capabilities, context, sequences, processes, the data model, and the API surface — and can refresh or sync the model — instead of reading source files. After code changes, the agent calls refresh (or you re-run amt analyze) so answers reflect reality.
Agents that don't speak MCP (Cursor, Copilot, plain LLM chats) read a repo context file. Archmantic auto-writes AGENTS.md from the same model — a concise, grounded summary in a managed block — on every analyze/update, so it never drifts. Refresh it anytime with amt knowledge; your own notes around the block are preserved.
Every tool call is recorded with the tokens it saved. See it in the terminal with archmantic usage, or on the team Usage dashboard (the MCP server flushes events to the cloud when a token is set).
Multi-repo systems#
Microservices or split front/back repos? Declare each repo's place in the larger system with .archmantic/config.json:
{
"system": "payments-platform",
"consumes": ["ledger-service", "notifications"]
}Push each repo, then open Systems for a unified cross-service context diagram and drill-down — no central config, each repo declares its own edges.
The Systems page also auto-links your repos: it flags inferred couplings (a repo imports something matching a sibling repo but hasn't declared it) and dangling ones (a declared consumes with no matching repo — a real gap), alongside the confirmed connected links.
CI / PR diffs#
A reusable GitHub Action comments on each PR with the architecture-level delta — new or removed components, capabilities, data-model entities, and external systems — not a line diff. It keeps a single sticky comment, updated on every push.
# .github/workflows/architecture-diff.yml
name: Architecture diff
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: mgionas/Archmantic@v1Inputs: base-ref (default: the PR base branch), working-directory, version, comment, and github-token. It runs archmantic diff under the hood — no install step needed.
Edit-then-build#
The model is a source you can edit, not just a read-out:
npx archmantic spec # emit an agent-ready build spec from the model
npx archmantic handoff # → an implementation plan (Claude, BYOK)
npx archmantic handoff --apply # autonomous agent edits the repo and self-verifiesEdit the BPMN canvas in the web app, apply it back into the model, emit a build spec, and hand it to an agent that implements and verifies (runs build + tests, fixes failures until green). Commit first; review with git diff.