Documentation

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

No install needed — run it straight from npm:

npx archmantic analyze
npx archmantic view

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

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 reads

analyze 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).

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 model

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

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 mcp

Claude 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).

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.

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@v1

Inputs: 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.

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

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