This Open-Source Tool Makes Claude Create Architecture Diagrams

AI Better Stack · 7m 27s · Watch on YouTube · 7 sources

Decision Card

Effort: One-evening trial, roughly 30-60 minutes: install the skill with npx skills add tt-a1i/archify -g, ask Claude Code one narrowly scoped question about a repo you already know well, and open the resulting HTML to check every node against the code.

Honest take: The video’s headline design claim, that “the model does not control the layout,” contradicts Archify’s own README, which says the agent “chooses hierarchy, spacing, routes, and emphasis” and lists “layout judgment over generic auto-layout” as a core principle; the compiler enforces geometry gates but does not lay the diagram out for you, so layout quality still depends on the model. The video also never shows a case where the validator or SRC evidence actually caught a hallucinated component, so the “verifiable” pitch is demonstrated only as a feature, not as a result.

Concrete next steps:

TL;DR

Archify is an MIT-licensed agent skill for Claude Code, Cursor, Codex, and OpenCode where the model emits typed JSON describing a system, a local Node.js compiler validates it and fails closed on errors, and only then renders an interactive self-contained HTML diagram with optional commit-pinned source evidence and snapshot diffs. The presenter finds it worthwhile for PR reviews and design docs when you ask one narrow question per diagram, but warns it does not know your architecture, cannot reverse-engineer a repo, and is a poor fit for README embedding where Mermaid still wins.

Key Points

  • The core idea is that the agent never draws; it outputs a typed graph that Archify validates and then renders, which is meant to stop invented components like a nonexistent API gateway. 00:13
  • Invalid JSON does not become a diagram. The pipeline fails and returns diagnostics, rule codes, and suggested repairs instead. 04:51
  • Archify is installed as an agent skill with a single command rather than a standalone app, and the same skill works across Claude Code, Cursor, and Codex. 01:20
  • The presenter’s prompt discipline: one question, 8-12 nodes max, only boxes that exist in the repo, omit anything unprovable, deliver self-contained HTML. 01:44
  • Nodes can carry repo evidence tied to a commit and line range; without that proof a node gets no SRC badge no matter how confident the prose sounds. 02:28
  • The HTML is interactive: search for a service, click to see upstream and downstream, and play a route to walk the cache-miss path rather than tracing arrows by eye. 02:50
  • For code review, Archify can diff two validated snapshots and report what was added, removed, moved, or rerouted, and committing the JSON lets the architecture persist into the next agent session. 03:49
  • The mental model offered is “LLVM for system maps”: agent as front end, JSON as intermediate representation, HTML as compiled output, with five modes: architecture, workflow, sequence, data flow, lifecycle. 04:09
  • Where not to use it: diagrams destined for a README, since GitHub renders Mermaid but not Archify HTML. 05:06
  • A valid graph can still describe the wrong system, so you must still read it; and pointing it at a huge repo with “map everything” is a bad question, not a tool failure. 05:56

Notable Quotes

“the agent doesn’t draw anything. It outputs a typed graph. Archify validates it and then renders the diagram.” 00:13

“the easiest way to understand Archify is this LLVM for system maps. The coding agent is the front end. The JSON is the intermediate representation. The HTML is the compiled result.” 04:09

“Archify does not know your architecture. A graph can be completely valid and still describe the wrong system. You still have to read it.” 05:56

Verified Claims

Claim: Archify picked up roughly 44,000 GitHub stars in a few months. 00:46 Sources: tt-a1i/archify on GitHub shows 54.5k stars as of this writing; explainx.ai’s guide dates the launch to 15 April 2026. Verdict: Confirmed. The exact number is a moving target and third-party snapshots disagree on interim counts, but tens of thousands of stars within about five months is accurate.

Claim: It is an agent skill installed with one npx command that works in Claude Code, Cursor, and Codex. 01:16 Sources: GitHub README lists npx skills add tt-a1i/archify -g and names Claude Code, Cursor, Codex CLI, and OpenCode as supported surfaces. Verdict: Confirmed. OpenCode is also supported, which the video omits.

Claim: There are five diagram modes: architecture, workflow, sequence, data flow, lifecycle. 04:30 Sources: SKILL.md and the project site. Verdict: Confirmed.

Claim: Nodes can include repo evidence tied to a commit and line range, shown as an SRC badge. 02:28 Sources: GitHub README states architecture nodes “mark themselves SRC n and open Git-verified files pinned to a specific public commit with exact line ranges,” and that this happens only when the user requests it. Verdict: Confirmed. Note the evidence is opt-in, so a default run produces source-free nodes.

Claim: Archify can diff two validated snapshots and report added, removed, moved, and rerouted changes. 03:49 Sources: README_EN.md documents the compare command with Before / Delta / After output and “added, removed, changed, moved, and rerouted facts.” The README also says the delta is reviewer-only and “infers no runtime impact.” Verdict: Confirmed.

Claim: You can copy a PNG or generate a 1200x630 share card. 03:09 Sources: GitHub README lists PNG clipboard copy and 1200x630 share cards; the project site adds SVG, WebM, JPEG, and WebP export. Verdict: Confirmed.

Claim: The model does not control the layout; it only describes the system. 04:36 Sources: README_EN.md says “the agent chooses hierarchy, spacing, routes, and emphasis” and lists “layout judgment over generic auto-layout” as a principle, while stating general-purpose auto-layout is out of scope. Verdict: Disputed. The compiler renders deterministically and rejects bad geometry, but layout intent is authored by the agent, not removed from its control.

Claim: The team tried themed Mermaid with automatic layout and it was no better than plain Mermaid. 04:43 Sources: README_EN.md says only that Archify “is not a general-purpose drawing editor or a Mermaid theme”; no published account of such an experiment was found. Verdict: Inconclusive.

Claim: Unknown JSON fields can fail validation. 04:25 Sources: SKILL.md stresses exact field naming and machine-readable repair diagnostics, but neither it nor the README states that extra fields are rejected. Verdict: Inconclusive.

Claim: GitHub renders Mermaid in a README but not Archify’s HTML. 05:12 Sources: GitHub docs on creating diagrams confirm native Mermaid rendering in Markdown files; github/markup documents that rendered HTML is sanitized to remove script tags, inline styles, and class or id attributes, which breaks an interactive self-contained HTML file. Verdict: Confirmed.

Tools, Papers & Standards Mentioned

Follow-up Questions

  1. How often does the validator actually reject hallucinated components in practice, versus accepting a structurally valid graph that describes the wrong system? A small benchmark on repos with known architecture would quantify the “verifiable” claim.
  2. Does committing Archify JSON alongside code stay maintainable over dozens of PRs, or does the compare/delta workflow drift once multiple agents edit the same snapshot? The README explicitly says the delta “infers no runtime impact,” so what review signal does it add beyond a code diff?
  3. Since the README says the agent authors hierarchy, spacing, and routes, how much does output quality vary across models (for example Claude versus Codex) on the same JSON task, and do the “two correction rounds” noted in third-party writeups suffice for weaker models?

Sources