Archify: an agent skill that compiles typed JSON into verifiable architecture diagrams

The problem Archify targets: diagrams that drift from the code

Most architecture diagrams are drawn once and then rot. The person who drew them leaves, the service names change, and nobody notices until an incident review. Archify's answer is to stop treating the diagram as the artifact and treat the typed description as the artifact. The README describes the project as a Node.js rendering and validation system for Cursor, Claude Code, Codex CLI and OpenCode, where agents produce typed JSON IR and Archify deterministically compiles it into HTML and SVG.

That split matters more than the rendering. Because the intermediate form is typed JSON, the same source can be validated, diffed, re-rendered in a different theme, and exported to several formats without a human redrawing anything. The README frames the audience narrowly: people who already drive an agent in a terminal or editor and want the diagram to come out of that same session. If you do not use one of those four agents, the core loop does not apply to you.

How the typed JSON IR becomes a self-contained HTML file

The data flow has three stages. An agent reads a codebase or a written system description and emits typed JSON IR. Archify validates and compiles that JSON deterministically. The output is a self-contained HTML file, with PNG, SVG, WebM and 1200x630 share cards available from the Export menu.

The repository layout backs this up. The examples directory holds paired files, such as examples/rag-pipeline.architecture.json next to examples/rag-pipeline.html, and examples/sequence-cache-miss.html next to examples/sequence-cache-miss-request.html. The naming convention carries the diagram type as a suffix, which tells you the compiler is type-aware rather than a generic graph renderer. The README lists five diagram types (architecture, workflow, sequence, data-flow and lifecycle) and four presets. A viewer directory and a generated directory sit at the top level, so the runtime is separated from produced artifacts.

Two design choices are worth flagging. First, the HTML is self-contained, which makes sharing trivial but means every artifact carries its own copy of the viewer. Second, motion is described as finite: guided stories play named chapters rather than looping animation. That is a deliberate constraint, and it is the reason the export to WebM is bounded in length.

Installing the Archify skill and producing a first diagram

The README gives a single global install command. It adds the skill to your agent's skill directory.

npx skills add tt-a1i/archify -g

For Cursor, the README documents an explicit non-interactive form with the skill name, agent and global flags spelled out, which is what you want in a scripted setup.

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

If you would rather not install anything, the README shows a one-off run against Codex.

npx skills use tt-a1i/archify@archify --agent codex

Once installed, the prompt is plain language. The README's own example asks the agent to map a repository's runtime architecture. A more bounded request, also from the README, constrains the scope so the agent does not try to draw everything.

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.

What you should see is a self-contained HTML file you can open locally. The README points to examples/web-app.html as a complete viewer to try without generating anything. Refinement happens in chat: the README lists follow-ups such as adding a node, moving a group, or highlighting a path, with the typed source retained for targeted iteration.

Where Archify breaks down or is the wrong tool

The most concrete limitation is the agent dependency. Archify is distributed as a skill for four named agents plus a separate DeepSeek Harness plugin and a manual ZIP path for Raven. There is no documented standalone CLI that takes a JSON file and writes HTML. If your workflow is a Makefile in CI, or a teammate who does not use any of those agents, you are outside the supported path.

The second limitation is scope control. The README's own example prompt spends three lines telling the agent to limit components, keep one primary path, and push detail into cards. That instruction exists because an unbounded request produces an unreadable graph. Archify validates the JSON, but validation is not the same as judgement about what belongs on the diagram.

The third is the claim boundary. The README is careful about the difference between authored reach and runtime impact: after tracing upstream or downstream reach, the Export menu captures that reading "without claiming runtime impact." If you need a diagram that reflects observed production traffic, Archify is not that tool. It renders what was authored, and it says so.

Archify compared with hand-drawn browser diagramming tools

The obvious alternative is a browser-based diagramming tool where a person drags boxes onto a canvas. The difference is not the visual quality of the output; it is where the source of truth lives. In a canvas tool, the diagram is the file, and the only way to review a change is to look at two images side by side.

Archify keeps the JSON as the reviewable object. The README describes comparing two validated snapshots as Before, Delta and After, with exact added, removed, changed, moved and rerouted facts. That is a different review workflow: you can read a text diff of the intermediate form before anyone looks at the picture. The repository even ships an example pair, examples/checkout-platform-delta.html with examples/checkout-platform-delta.receipt.json, which suggests the delta output comes with a machine-readable receipt.

The trade-off runs the other way too. A canvas tool lets you nudge a label two pixels to the left and be done. Archify's layout is deterministic, so if the compiled result places something awkwardly, your lever is the input JSON or the preset, not the canvas.

Licence, maintenance and what an upgrade costs

Archify is MIT licensed, and the repository carries a THIRD_PARTY_NOTICES.md alongside LICENSE. MIT is permissive, so redistribution and commercial use are not restricted by the project's own terms, but the bundled viewer and any dependencies listed in the notices carry their own terms. Read the notices file before shipping a generated artifact inside a product; that is an engineering step, not a legal opinion.

On maintenance, the last push was on 2026-08-17, and the most recent tagged release, v2.15.0, carries the same timestamp. The README states the current development version is v2.16.0-dev.0. There is a CHANGELOG.md and a ROADMAP.md at the top level, plus separate PRODUCT.md, DESIGN.md and REVIEWING.md documents, which is more process documentation than most projects of this size ship.

Upgrade cost is low in one direction and worth checking in the other. Upgrading the skill is another npx invocation. But the artifacts you already generated embed their own viewer, so an older HTML file keeps the behaviour it was built with. If you care about consistency across a set of diagrams, regenerate them together rather than mixing versions. The README also notes a separate integration package, @tt-a1i/[email protected], installed through dsh plugin, which versions independently of the main skill.

Editorial conclusion

Adopt Archify if you already work inside Cursor, Claude Code, Codex CLI or OpenCode and want diagrams that come out of the same chat as the code reading, with typed JSON you can diff before a merge. Skip it if your team draws diagrams by hand in a browser tool, or if you need a hosted service with accounts and shared workspaces, because Archify installs as a skill and produces files. Before committing, verify three things yourself: that the install path for your agent matches the agent switcher page, that the diagram type you need is one of the five the README lists, and that the export formats your review process requires are actually generated by the version you install. The repository's last push was on 2026-08-17 and the current development version is v2.16.0-dev.0, so pin the release you validate rather than tracking the development branch.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes