Archify: the trending agent skill that makes coding agents draw diagrams that check themselves

Archify is an agent skill for Cursor, Claude Code, Codex CLI, and OpenCode. Install it once with npx skills add tt-a1i/archify -g, describe a system in chat (or point it at a repository), and your coding agent hands back an interactive diagram as a single self-contained HTML file. As of this writing it tops the GitHub Trending chart with about 46,700 stars, roughly 24,200 of them added in the last seven days.

The reason to look past the chart position: agents here never draw.

The agent specifies, the tool renders

Every coding agent can already free-hand a Mermaid diagram. The output looks plausible and is frequently wrong, and nothing checks it. Archify flips the pipeline. The agent emits a typed JSON intermediate representation first, and Archify, a Node.js rendering and validation system, compiles it deterministically into HTML/SVG. Ask for Browser -> API -> Redis cache -> PostgreSQL fallback and the agent writes a schema-valid structure. The agent chooses the hierarchy, spacing, routes, and emphasis, while the renderer compiles that intent deterministically, so the same input always produces the same diagram.

That split is what makes the output verifiable instead of merely pretty. Bundled validators check schema, layout, generated HTML/SVG, routes, and label clearance before anything is delivered. When a check fails, validate --json and deliver --json return repair receipts: a stable rule code, the exact subject, measured evidence, and the supported fix, which the agent can apply and retry. The tool would rather say no than ship a broken diagram.

Andrea Losavio, who used it to map the runtime of his own site, watched it say no four rounds in a row. First a label overlapped a component. He had left 74 pixels of clearance and the label needed 87. Then the diagram came out 1992 pixels wide, which would have rendered node text at 4.2 pixels on a 1440 pixel laptop. Finally, a check that opens the file in Chrome at four resolutions rejected an artifact that had passed all nine earlier checks, because it stood 49 pixels too tall to fit on screen at 1440x900. "A tool that only agrees with itself would never have said that."

Five diagram types, one HTML file

Archify covers architecture, workflow, sequence, data-flow, and lifecycle diagrams. Four presets, Classic, Signal Flow, Blueprint, and Editorial, share one geometry contract and ship with coordinated dark and light themes. The output is one HTML file with zero dependencies: no server, no runtime, open it in any browser. Exports are the practical part: PNG and WebP rasterized at up to 4x, a dual-theme SVG that follows prefers-color-scheme in a README, WebM for motion, clipboard copy for Slack or Notion, and a 1200x630 share card for social posts.

The viewer is where the diagram stops being a picture. Click a node to see what it touches upstream and downstream, probe the shortest authored path between two components, compare semantic roles, or play a guided walkthrough that lights only the nodes you are talking about. Every view state has its own URL. Losavio's point is a good one: #route=source~seo tells someone on a call exactly which path you mean, in a way a cropped screenshot never could.

For review, there is compare: two validated snapshots become a Before/Delta/After view with a machine receipt that names exactly what was added, removed, changed, moved, or rerouted.

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

The docs draw a careful line here, and it is worth respecting. The delta compares authored facts. It does not infer runtime impact, risk, or merge safety, and it does not replace tests or a human review.

What to check before you trust one

Two independent hands-on write-ups land on the same warning. Archify validates structure; it does not guarantee the agent understood the code. It catches malformed data, invalid references, and layout problems, but "you still need to review the result", as Aditi Gupta puts it. The agent still authors the JSON, and repository evidence is optional, so validation does not make hallucination impossible.

Two consequences follow from that:

• Diagrams do not sync with the repository. When the architecture changes, you rerun the agent. That is still a win: regeneration is cheaper than manually redrawing, and it makes architecture docs feel like a build artifact rather than a drawing someone has to remember to maintain.

• Big repositories burn tokens. The README's own example prompt caps a diagram at 8 to 12 core components and one primary path; Gupta's review makes the same point about cost. Do not open with "diagram the entire monorepo".

Evidence-backed mode is the built-in answer to "trust me, I read the code". Architecture nodes can mark themselves SRC n and open repository files and line ranges pinned to a specific public commit, verified by Archify before the link is published. That turns the diagram into claims you can click through to source instead of a wall of boxes. Gupta calls this the most valuable part of Archify; Losavio flags the practical limit, that nodes citing real files need a public remote and a pinned commit, so an unpushed branch is out.

Where it sits

Archify is based on Cocoon-AI/architecture-diagram-generator; the project page footer credits that project as its basis. The scope section is explicit about what it is not: automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are out. You fix things by asking in chat. Losavio puts the trade in context: for an eight-node diagram inside a README, Mermaid still wins, because its source reads cleanly in a git diff. Archify targets the other case: the map you want before you rework a system you do not fully hold in your head, that you can actually hand to someone.

It requires Node.js 18 or newer, and development is moving quickly: 2.15.0 landed August 17 with 107 provenance-backed brand marks, 2.16.0 landed August 30 with a constraint-driven workflow compiler and English and simplified Chinese viewer localization, and the tree is already on 2.17.0-dev.1 (a development version, not a stable release). The license is MIT.

The whole project comes down to one choice: do not make the LLM draw, make it specify. Drawing becomes deterministic, checkable, repeatable; judgment stays with the model, which is where you want to spend the tokens anyway. If you have to understand a system before you change it, that trade is worth a look.