Every developer knows the drill: you finish a feature, someone asks for an architecture diagram, and you end up dragging boxes around in a drawing tool for an hour. Archify skips that step entirely. It’s an open-source agent skill that reads a plain-English description or an actual code repository and turns it into an interactive, self-contained HTML diagram, without you ever opening a canvas editor.
What makes this interesting isn’t just the automation. It’s that Archify plugs directly into the coding agents developers already use, Cursor, Claude Code, Codex CLI, and OpenCode, so the diagram gets generated right inside a chat session. In other words, you ask your agent to map the runtime, and a few seconds later you have a file you can open in any browser.
Why architecture diagrams keep falling out of date
The real problem with diagrams has never been drawing them once. It’s keeping them honest after the third refactor. Because most teams treat diagrams as a one-time deliverable for a design doc, they quietly rot the moment the code moves on, and nobody notices until an incident review needs a map that no longer matches reality.
Archify approaches this differently by making the diagram a byproduct of describing the system rather than a separate drawing task. The project’s own framing captures this well: it is meant to turn a codebase or system description into a polished, interactive system map, directly in chat. Since the agent produces a typed JSON source behind every diagram, the same description can be edited and re-rendered instead of redrawn from scratch.
A rendering layer, not a drawing app
It’s worth being precise about what Archify actually is. It is a Node.js rendering and validation system: the agent produces typed JSON intermediate representation, and Archify deterministically compiles that into HTML and SVG. Archify itself doesn’t understand your code or write the description; the coding agent does that part, and Archify’s job is to turn the structured result into something trustworthy and shareable. That distinction matters because it explains why the tool works consistently across four different agent environments: the JSON contract stays the same regardless of which agent authored it.
How the plain-English-to-diagram pipeline actually works
The workflow breaks into five stages. First, the agent generates typed JSON IR from your description or from the repository it just analyzed. Next, bundled validators and layout rules check that source, and if something’s wrong, the failure identifies the exact local repair in machine-readable JSON rather than a raw stack trace. There’s an optional preview stage after that: a loopback-only desktop session watches a single JSON file and reloads only the revisions that pass validation, so a bad save never overwrites the last good diagram on screen.
Once validation passes, delivery happens atomically: a candidate renders in the same directory, gets checked again, and only a passing artifact replaces the target file. Finally, you iterate, asking your agent to add a service or move a node, and the underlying JSON updates while the rest of the structure stays put. This atomic delivery model is why the project can promise deterministic output instead of “mostly right most of the time.”
Five diagram types for five different questions
Archify doesn’t try to be one diagram shape that fits everything. It ships five distinct renderers, each tuned to a different kind of question:
Architecture, for mapping components, services, storage, and trust boundaries
Workflow, suited to CI/CD pipelines, approvals, and runbooks
Sequence, for API calls, cache fallback logic, and async traces over time
Data Flow, which makes movement and PII boundaries explicit across pipelines
Lifecycle, for states, retries, waits, and terminal outcomes
If you’re not sure which one fits your question, the project has a scenario guide, or you can ask the zero-dependency CLI directly with a command like node archify/bin/archify.mjs guide "Show an API request with Redis cache miss".
What you actually get back: real benefits beyond a pretty picture
The headline feature is that everything renders to one self-contained HTML file with zero dependencies: no server, no runtime, no build step on the reader’s end. You can attach it to an email or drop it in a pull request comment, and it opens correctly in any browser. That alone solves a real pain point, because most diagram tools either lock output behind a hosted viewer or require the reader to install something first.
Exports built for both screens and print
Beyond the HTML itself, Archify exports PNG, JPEG, and WebP raster images natively at up to 4× source resolution, so slides and printed docs stay sharp instead of blurry on retina displays. SVG exports go a step further: they ship dual-theme, carrying both light and dark variable sets alongside a @media prefers-color-scheme rule, so a single SVG dropped into a GitHub README automatically follows the reader’s system theme. There’s also a dedicated share-card export at 1200×630 for README headers or social posts, and a route-specific share card that keeps the full diagram visible as context around one traced path.
Reviewing what actually changed between two versions
One feature that stands out for teams doing design or PR review is Architecture Delta. Instead of eyeballing two screenshots side by side, you compare two validated snapshots as Before, Delta, and After, and Archify produces a machine receipt of exactly what was added, removed, changed, moved, or rerouted. Running it is a single CLI call: node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json. It’s explicitly viewer-only, meaning it won’t guess at risk or merge-safety, it just shows you the authored facts that changed.
Interaction that stays grounded in what was actually authored
Once a diagram is open, you can search for a node, trace its upstream or downstream reach, probe the exact route between two components, or compare two semantic roles side by side. Keyboard shortcuts drive most of this: / to find a node, R to probe a route, L to open the role-comparison lens, and F to enter a presentation stage. Because these interactions reuse the authored nodes and relationships rather than inferring new ones, they never claim a runtime impact the diagram didn’t actually record.
Getting Archify running: installation and first diagram
Installing the skill via npx
Getting started takes one command:
npx skills add tt-a1i/archify -gFor an explicit, non-interactive Cursor install, the project provides a more specific variant:
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yesIf you’d rather try it without committing to an install, there’s a one-off run mode too: npx skills use tt-a1i/archify@archify --agent codex. The agent switcher on the project page covers cursor, codex, claude-code, and opencode specifically. Raven works differently: since it isn’t a switcher target, you extract archify.zip manually into ~/.raven/workspace/skills, which yields ~/.raven/workspace/skills/archify.
Asking for your first diagram
Once installed, you just talk to your agent. A bounded first request looks like this:
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.Notice the instruction to cap it at 8 to 12 components. That’s a deliberate constraint the project recommends, because a diagram trying to show every single service tends to become unreadable. After the first draft, you keep refining conversationally: “add Redis,” “move auth to the left,” or “highlight the rollback path,” and Archify keeps the typed JSON source available for that kind of targeted iteration rather than regenerating the whole thing from scratch.
A real repository mapped from source
The project demonstrates this against a real public repository, tracing mco-org/mco at a specific commit to produce a checked architecture map with a dispatch-path view. That example matters because it shows the pipeline working against actual, messy source code rather than a hand-picked toy description, which is a fair test of whether the natural-language-to-diagram approach holds up outside a demo.
Where this fits for production reviews, and where it stops
An engineering profile for deployment reviews
For production deployment review specifically, the Architecture renderer can optionally enable a deployment-ownership profile. It fails closed, meaning it deliberately blocks delivery, when owners, single-region placement, private database scope, or named boundary crossings are missing from the source. This is never turned on silently, and it checks the facts you authored rather than pinging live infrastructure to verify anything.
What Archify deliberately doesn’t do
The project is explicit about scope, and this is refreshing in a space full of tools that try to do everything. Archify states plainly that automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside its current scope. It also draws a clear line around its own identity: it is not a general-purpose drawing editor or a Mermaid theme, but a way to turn technical intent into a communication artifact. If you need a freeform whiteboard tool, this isn’t it; if you need a diagram that stays synchronized with a description an agent can regenerate, that’s the actual target.
Community integrations and licensing
Archify also has a community-built integration for DeepSeek Harness, installed via dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0. The project is explicit that this is a community integration and not an official DeepSeek product, and that it involves no telemetry. The whole project ships under the MIT license, meaning it’s free to use, modify, and distribute, which matters if you’re planning to fold it into an internal tooling pipeline. Sponsorship comes from APINEBULA and from EverMind, whose Raven memory infrastructure project supports Archify as an installable skill for verified system maps.
People Also Ask
Can Archify analyze a code repository and create a runtime architecture map?
Yes. The project’s own example traces the public mco-org/mco repository at a specific commit and produces a checked architecture map from it, complete with a dispatch-path view. The agent reads the repository first, then hands Archify a typed JSON description to render, rather than Archify parsing source code on its own.
How does the Architecture Delta comparison work between two diagram snapshots?
You run a CLI command pointing to a base and head JSON file, and Archify produces a Before, Delta, After comparison along with a machine-readable receipt of exactly what was added, removed, changed, moved, or rerouted. It’s viewer-only by design, so it never infers merge risk or safety, it just reports the authored facts that changed.
Does Archify work with DeepSeek Harness or only with Cursor, Claude Code, and Codex?
There’s a community-maintained integration for DeepSeek Harness installed through dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0, though the project is clear this is a community effort, not an official DeepSeek product, and it involves no telemetry. Beyond that, Archify’s full renderer and validation workflow targets Raven, Cursor, Claude Code, Codex CLI, and OpenCode.
If you’re already living inside an agent-driven workflow, Archify is less a new tool to learn and more a skill you bolt onto the agent you’re already talking to. The atomic validation and typed JSON source are what separate it from a quick Mermaid sketch: you get a diagram that fails loudly when it’s wrong instead of quietly rendering something misleading. For teams that review architecture changes as part of code review, the delta comparison alone might be worth the install.
Additional Resources
This article includes content created with AI.