Set up Archmantic

Point Archmantic at a repo and it reverse-engineers a single architecture model (the IR). Every diagram — C4-style context, components, sequence (interactive graphs), an auto-detected business process, and an ERD of your data model (from Prisma, Drizzle, SQL, or Laravel migrations), plus a detected API surface (REST/tRPC/GraphQL, incl. NestJS and Laravel routes) — 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).

Archmantic is polyglot — it detects, per layer:

• Languages — TypeScript / JavaScript and PHP.
• Frontend / components — React & Vue (.vue SFCs), including Inertia resources/js/Pages, plus Blade templates and Livewire components. Each is role-classified (page, route, ui, layout, view, model, hook, store, …).
• API surface — Next.js (App Router & Pages), Express / Fastify / Koa / Hono, NestJS decorators, Laravel routes/*.php (prefix groups + resource/apiResource), tRPC, and GraphQL.
• Data model (ERD) — Prisma, Drizzle, SQL CREATE TABLE, and Laravel migrations (Schema::create + foreign keys). Framework scaffolding tables are filtered out.
• Tech stack — detected from package.json and composer.json (Laravel, Inertia, Livewire, Sanctum, …).

No install needed — run it straight from npm:

npx archmantic analyze
npx archmantic view

Or install the CLI globally:

npm install -g archmantic
archmantic analyze

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.

The recommended way to use Archmantic in Claude Code. The plugin auto-registers the MCP server and ships a skill so your agent reaches for the model on its own — instead of reading whole files — when it onboards to or reasons about a repo. (A bare MCP server is passive; with many plugins installed, agents tend to overlook it. The skill is the behavioral nudge that fixes that.)

/plugin marketplace add mgionas/Archmantic
/plugin install archmantic@archmantic
npx archmantic analyze        # build .archmantic/model.json once per repo (commit it)

It also adds an /architecture command for an on-demand, grounded overview. To skip the per-tool permission prompt, add one rule to your .claude/settings.json (plugins can't set permissions for you):

{ "permissions": { "allow": ["mcp__archmantic__*"] } }

Prefer a reads-only allow-list? List the read tools explicitly so the write tools (refresh/sync/sync_features/curate) stay gated — see the plugin README.

Prefer to wire it yourself, or using another host (Claude Desktop, Cursor, …)? Build the model once, then register the server directly — you don't run it by hand.

archmantic 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 reads the project brain (get_project — goal, owner, agent team, links, history), the features (list_features/get_feature — what the product does), and queries components, capabilities, context, sequences, processes, the data model, and the API surface; gets cross-repo link suggestions (suggest_links); and can refresh or sync the model — instead of reading source files. After code changes, the agent calls refresh (or you re-run archmantic 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 archmantic 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).

One repo, many packages? Archmantic analyzes a monorepo as a single model. It reads your declared workspaces (npm/yarn workspaces, pnpm-workspace.yaml) and falls back to convention (apps/*, packages/*, services/*, …), so an undeclared Turborepo/Nx layout works too.

Every component, endpoint, and data entity is tagged with its owning package, and the project view lets you group Components and the API by package (with a “Monorepo · N packages” overview). An independent nested app that isn't a workspace member stays out of the model.

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

Refine the model — capabilities, features, the process — then 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.