archify for Claude Code and Codex: architecture diagrams that pass checks before delivery

archify is a skill that turns a system description or a codebase into an interactive HTML architecture diagram. It ships as a single skill with a Node.js CLI, and the repository is public under the MIT license. This post covers the problem it solves, who it suits, how to install it and make the first request, and the details worth knowing before you put its output in front of a review meeting.

What problem it solves

Asking an agent for an architecture diagram usually gets you something that looks fine at first glance. Then you notice an arrow that crosses a label, a box that overlaps another, or a layout that shifts completely the next time you ask for a small edit. The diagram has no source you can reason about, so every revision starts over.

archify works from a typed JSON source instead. The agent first picks a diagram type with guide, which recommends one of five types the README lists: architecture, workflow, sequence, data flow, and lifecycle. It then writes the JSON and runs finalize, which chains validate and deliver. Validation checks layout, paths, and label overlaps, and when something fails it returns rule codes and the items to fix as JSON. Only HTML that passes every check is kept, and the on-screen export menu offers PNG and SVG. Because the layout compiles from the same source, it stays consistent after edits.

Who it fits

The chapter rates four situations. Three cover most decisions.

Situation	Fit	Reason
A single architecture diagram for a planning review	Good fit	Creates a diagram from a description
A flowchart for a presentation	Good fit	Can export PNG
Creating brand posters	Poor fit	Not a general-purpose drawing tool

If you expect to drag boxes around by hand afterward, look elsewhere. The README states that direct drag-and-drop editing is outside its scope.

Install and first run

One command installs it globally, and Codex can also run it once without installing.

# Install globally
npx skills add tt-a1i/archify -g
# Codex: use once without installing
npx skills use tt-a1i/archify@archify --agent codex

According to the README, the skill lands in ~/.claude/skills/ for Claude Code and ~/.agents/skills/ for Codex CLI. Rendering and validation need Node.js 18 or later. After that, the first request is a single sentence.

Turn [system description] into an architecture diagram

The generation rules live in archify/SKILL.md, and the CLI commands run after node bin/archify.mjs if you want to call them yourself.

What trips people up

A passing diagram is not a verified system. archify validates the drawing, not your infrastructure, so the boxes and arrows reflect exactly the relationships you described. If your description is missing a queue or gets a dependency backwards, the diagram will be clean and wrong. Treat it as a picture of your claim, and check runtime behavior separately. Two smaller notes: package.json requires Node 18 or later, and the CLI queries a fixed manifest about every 24 hours to check for new versions. Set ARCHIFY_UPDATE_CHECK_DISABLED=1 if you do not want that call.

Where this comes from

This post adapts part of chapter 04-02 of The Claude Code & Codex Skills Guidebook. The full chapter covers the complete command table, including preview for validated versions, and how compare reports additions, deletions, and moves between two architectures, and the book has 52 more skills like this one. Read the full chapter in The Claude Code & Codex Skills Guidebook on Gumroad.