TL;DR

Archify (tt-a1i/archify) is an agent skill for Cursor, Claude Code, Codex CLI, and OpenCode that turns a codebase or a one-line system description into a polished, interactive architecture diagram — as a single self-contained HTML file. The agent writes a small typed JSON intermediate representation; Archify’s Node.js CLI validates it against a schema and a set of layout rules, then deterministically compiles it into HTML/SVG with dark/light themes, finite “trace” motion, and PNG/SVG/WebM export.

It is the fastest-growing agent skill on GitHub right now: 61,519 stars and 4,052 forks as of 14 September 2026, with roughly 10,100 stars added this week. Five diagram types, MIT licensed, zero runtime dependencies beyond Node.

Key facts:

  • 61,519 stars / 4,052 forks, created 15 April 2026, last push 14 September 2026, MIT
  • Development version v2.17.0-dev.1; last stable release v2.16.0 on 30 August 2026
  • Install: npx skills add tt-a1i/archify -g (Cursor, Claude Code, Codex CLI, OpenCode)
  • No Mermaid parser, no auto-layout engine — by design, after a blind test the author ran and failed
  • Every diagram passes validate (9 artifact checks) before deliver atomically replaces the output file
  • Own benchmark: ordinary models produce a first-pass-usable diagram 53% of the time (8/15 runs)
  • Based on Cocoon AI’s architecture-diagram-generator v1.0 (MIT), rewritten from v2 onward

What it actually does

Ask Claude Code for an architecture overview and you get a Mermaid block that renders into a grid of evenly spaced boxes with crossing arrows. Technically correct; nobody puts it in a design doc.

Archify’s argument is that the hard part is not the boxes, it’s the layout judgment: which component sits outside the trust boundary, what goes below what, which path is the main one. The skill makes the model do that judgment explicitly, then makes a deterministic renderer enforce that the result is readable.

StageWhat happens
GenerateThe agent reads one schema and one example, then writes a typed JSON file with components, boundaries, connections, and cards
Validatearchify validate runs schema, layout, HTML/SVG, route, and label-to-route clearance checks; failures come back as machine-readable diagnostics with supportedFixes
Deliverarchify deliver renders a candidate next to the target and only replaces the last-good output if every gate passes
IterateYou say “add Redis” or “move auth to the left” and the agent edits the JSON, not the picture

The output is one HTML file (~800 KB — it embeds the viewer, a JetBrains Mono subset, and the SVG) that works offline. Inside the viewer you can search nodes (/), trace upstream/downstream reach, probe a directed route (R), compare two semantic roles (L), play a guided story chapter (P), switch presets and themes (S/T), and export PNG, SVG, WebM, or a 1200×630 share card (E). Every interaction reuses the authored nodes and edges — the viewer never invents topology.

Install and first diagram

Global install for whichever agent you use:

npx skills add tt-a1i/archify -g

# Cursor, explicit and non-interactive:
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

# Try without installing:
npx skills use tt-a1i/archify@archify --agent codex

Then, in any agent chat — no repository required:

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

Or, with a repo open, the prompt the README recommends:

Analyze this repository, then use archify to create a high-level runtime
architecture diagram. Show 8–12 core components, one primary path, external
dependencies, and trust boundaries. Put supporting detail in cards instead
of adding more edges.

That last sentence is doing real work: the authoring contract caps a showcase diagram at 12 primary nodes and pushes everything else into side cards.

The JSON IR, and why it matters

A trimmed version of the bundled web-app.architecture.json example, so you can see what the agent actually writes:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample Web App",
    "quality_profile": "showcase",
    "views": [{ "id": "request-path", "label": "Primary request path", "focus": ["users", "api", "db"] }]
  },
  "components": [
    { "id": "users", "type": "external", "label": "Users", "pos": [40, 300], "size": [120, 60] },
    { "id": "auth",  "type": "security", "label": "Auth Provider", "sublabel": "OAuth 2.0",
      "pos": [40, 110], "size": [120, 64], "tag": "JWT + PKCE" },
    { "id": "api",   "type": "backend",  "label": "API Server", "sublabel": "FastAPI :8000",
      "pos": [670, 300], "size": [130, 60] },
    { "id": "db",    "type": "database", "label": "PostgreSQL", "pos": [880, 300], "size": [130, 60] }
  ],
  "boundaries": [
    { "kind": "region", "label": "AWS Region: us-west-2", "wraps": ["api", "db"] }
  ],
  "connections": [
    { "id": "users-to-cdn", "from": "users", "to": "cdn", "label": "HTTPS", "variant": "emphasis" },
    { "id": "jwt-verification", "from": "auth", "to": "api", "label": "verify JWT", "variant": "security" },
    { "id": "api-sql", "from": "api", "to": "db", "label": "SQL" }
  ],
  "cards": [
    { "dot": "rose", "title": "Security", "items": ["OAuth 2.0 with JWT + PKCE"] }
  ]
}

Three things to notice. Positions are explicit — the model decides auth floats top-left outside the AWS region because it is not an AWS resource; that is the layout judgment Archify is betting on. IDs are stable, so “add a queue” is a diff, not a regeneration. And meta.views defines named views you can deep-link to (#view=request-path), which is how guided stories work.

Validation is the piece that makes this more than a pretty template:

cd ~/.claude/skills/archify
node bin/archify.mjs doctor
node bin/archify.mjs validate architecture my-system.json --quality showcase --json
node bin/archify.mjs deliver  architecture my-system.json my-system.html --quality showcase --open --json

A showcase pass must report all nine artifact checks with zero errors and zero warnings. On failure you get one JSON object with a stable rule code, the exact subject (which edge, which label), measured evidence (overlap in pixels), and a short list of supportedFixes. The skill tells the agent to apply only those fixes, one geometry control per repair, and to stop after two rounds without improvement — a guardrail against the “tweak coordinates for twenty turns” failure mode.

The other standout command is archify compare architecture base.json head.json delta.html --json, which produces an Architecture Delta — a Before / Delta / After artifact listing exactly which nodes and edges were added, removed, changed, moved, or rerouted between two validated snapshots. That is the feature I would put in a PR template.

The experiment that killed auto-layout

The most interesting file in the repo is not code. It is experiments/v3-mermaid-validation/RESULT.md, where the author pre-registered a blind test before building a Mermaid importer.

Three versions of the same diagrams were rendered: A = stock Mermaid via mmdc with dagre layout, B = the same dagre layout with Archify’s dark palette and JetBrains Mono applied as theme CSS, and C = Archify’s hand-placed layout with the model assigning semantic classes and coordinates. Screenshots were shuffled and labels stripped. The pass criterion for building a Mermaid parser: B averages ≥ 7/10 and lands closer to C than A in at least 4 of 5 diagrams.

The owner’s self-evaluation is one line: “C looks good; A and B both don’t look good. B is not meaningfully better than A.” The decision box is checked FAIL. The Mermaid → dagre parser was killed, and the ROADMAP now says “auto-layout (dagre / elk-js) is a dead end for archify” and that “prettier Mermaid renderer” is already taken by projects like lukilabs/beautiful-mermaid and Mermaid 11’s own ELK layout.

The conclusion — layout is the product, not CSS — is the whole thesis. Archify accepts pasted Mermaid flowchart, sequenceDiagram, and stateDiagram, but the skill says to read it “for topology and meaning, then author fresh Archify JSON,” not to convert it mechanically. A real flowchart importer (archify import flowchart) is open as issue #140.

It is refreshing to see a project publish the negative result and the roadmap items it killed. (A September 2026 provenance cleanup removed two of the five test diagrams over redistribution licenses; the result file says so rather than quietly rewriting the criterion to 2-of-3.)

What the benchmark says about weaker models

Archify ships its own benchmark, benchmarks/ordinary-model-floor/, asking one narrow question: can an ordinary coding agent produce a usable diagram on attempt one, with no human editing the JSON? “First-pass usable” requires correct semantics, a passing validate --quality showcase, and a named reviewer recording no visual defects. The published matrix from 26 July 2026 (Pi agent, packaged skill, 30-minute limit, five cases each):

ModelRunsFirst-pass usableFailure clusters
MiniMax M354 (80%)1 semantic, 1 visual review
Qwen 3.7 Plus52 (40%)1 semantic, 3 validation, 3 visual
DeepSeek V4 Flash52 (40%)3 validation, 3 visual
Overall158 (53%)2 semantic, 6 validation, 7 visual

With mid-tier open models, expect roughly a coin flip on the first attempt, with most failures being layout-validation and visual problems rather than wrong topology — which is exactly what the repair loop exists for. There is no published Claude/GPT matrix, an odd omission for a project this popular, and the harness deliberately does not launch model providers, so these are the author’s runs, not a leaderboard.

Community reaction

Archify’s growth pattern is unusual: enormous on GitHub, nearly invisible on Hacker News (the one HN submission, 7 September 2026, scored a single point). The traction came from the Chinese developer community — the README links to the LINUX DO forum and ships a full README_ZH.md. A Juejin roundup of the 6 September GitHub weekly chart noted four of the top five star-gainers were agent skills, with Archify leading, framing it as “skill packs replacing models as the stars of the chart.”

English coverage has mostly been aggregator blogs tracking the star count (20K → 36K in five days in late August) rather than hands-on reviews; a 30 August r/LovingAIAgents thread got little discussion. The one substantive outside take positions it as a free alternative to Structurizr’s retired cloud service.

The GitHub issue tracker is where the real conversation is: per-lane workflow heights (#255), the Mermaid importer (#140), a code-analyzer “extract step” producing raw-facts.json before authoring (#352), an entity-relationship diagram type (#399), and a “cognition” type for reasoning-route diagrams (#150). The project has CODEOWNERS, a REVIEWING.md, CodeRabbit config, and a reproducible bug-report form — a maintained project, not a weekend repo with a viral README.

Honest limitations

It is not a drawing tool. No WYSIWYG editor, no drag-and-drop, no hosted sharing. To nudge a box you edit pos: [670, 300] in JSON and re-deliver. The README lists Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing as intentionally out of scope.

Output files are heavy. Every delivered HTML is ~800 KB because the viewer, font subset (~96 KB), and SVG are inlined for offline self-containment. Fine for a design doc, awkward for committing fifty of them.

Model quality is the ceiling. 53% first-pass on ordinary models is the honest number. Frontier models do much better in practice, but you still depend on the model’s spatial judgment, and the repair loop can burn a few thousand tokens on a stubborn label-clearance error.

Repo tracing is not code analysis. “Analyze this repository” means the agent reads code the way it always does. SRC n evidence badges pin nodes to Git-verified files and line ranges, but no static analyzer builds the graph — that is what issue #352 proposes.

Twelve-node cap and rapid churn. Showcase profiles cap primary nodes at 12, so large microservice estates get split into several diagrams with named views. And v2.16 shipped a new workflow compiler (schema v2) on 30 August with v2.17 already in development; schema v1 stays byte-stable, but pin a version if you build tooling around the JSON.

Who should use it

  • Engineers writing design docs and RFCs in Claude Code or Cursor — the best “give me a diagram I would actually paste into the doc” tool I have tested.
  • Teams reviewing architecture changes in PRs — Architecture Delta is a genuinely new workflow: two validated snapshots, one receipt of what moved. Skip it if you need a collaborative editor (Excalidraw, tldraw) or automatic diagrams from static analysis of a large codebase.

FAQ

Does Archify replace Mermaid? No. It refuses to be a Mermaid renderer — the author blind-tested “Mermaid + nice CSS” against hand-placed layouts and found the CSS made no meaningful difference. Archify accepts pasted Mermaid as input for topology, then the agent authors fresh typed JSON with explicit coordinates. Mermaid remains right for quick inline diagrams in Markdown.

Which agents does it work with? Officially Cursor, Claude Code, Codex CLI, and OpenCode via npx skills add tt-a1i/archify -g. Raven via manual ZIP, DeepSeek Harness via an opt-in community plugin (@tt-a1i/archify-dsh), and Claude.ai by uploading archify.zip if the sandbox has Node.js.

Is it free? Any telemetry? MIT licensed. The only network call is an optional update-reminder check roughly every 72 hours that sends no project data; disable it with ARCHIFY_UPDATE_CHECK_DISABLED=1. Rendering and validation are entirely local.

What are the five diagram types? Architecture (components, boundaries, infrastructure), Workflow (CI/CD, approvals, runbooks), Sequence (API call chains), Data Flow (pipelines, lineage, PII boundaries), and Lifecycle (state machines with retries and terminal states). Architecture has an optional deployment-ownership profile that fails closed unless owners, regions, and named boundary crossings are authored.

How reliable is the first attempt? The project’s own benchmark puts ordinary open models at 53% first-pass usable across 15 runs (MiniMax M3 80%, Qwen 3.7 Plus and DeepSeek V4 Flash 40%). Frontier models do better in practice, and the validate/repair loop is designed to close the gap within two correction rounds.

Can I diff two versions of an architecture? Yes — archify compare architecture base.json head.json delta.html --json produces a Before / Delta / After artifact plus a JSON receipt of added, removed, changed, moved, and rerouted nodes and edges. It describes authored facts only; it does not infer risk or merge safety.

Bottom line

Archify is the rare viral agent skill with a real engineering thesis under the star count. Make the model do layout judgment, then validate deterministically instead of trusting an auto-layout engine — backed by a published negative experiment, a schema-per-type IR, a nine-check validation gate, and a repair loop with a stopping rule. The output is the first agent-generated architecture diagram I would put in a design review without redrawing it.

The caveats: it is a generation pipeline, not an editor, each artifact is ~800 KB of HTML, and weaker models clear the bar about half the time on the first try. If you are on Claude Code, Cursor, or Codex CLI and you write design docs, install it: npx skills add tt-a1i/archify -g. If you were hoping for “make my Mermaid pretty,” the author already tested that idea and killed it.

Sources