Archify

An open-source skill by tt-a1i (tt-a1i/archify).

What it does

Hand-drawn architecture diagrams drift from the code. Generic auto-layout piles arrows onto one midpoint. Ask an agent for a diagram and it can quietly invent an edge that does not exist.

Archify splits the two jobs. The agent writes typed JSON IR and nothing else; Archify compiles it. “Atomic validation before delivery — schema, layout, HTML/SVG, route, and label-to-route clearance checks must all pass before a showcase artifact replaces the last known good output.” When a check fails you get a repair receipt rather than a stack trace: “validate --json and deliver --json return stable rule codes, the exact subject, measured evidence, and only supported repair controls.”

What you end up with is one HTML file — open it, present it, share the link, export it.

What you can build

Five diagram types, each with the detail worth putting in the prompt:

Start from a description, no repository needed:

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

Or from source:

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.

Then refine in chat with focused requests such as add Redis, move auth to the left, or highlight the rollback path — “Archify keeps the typed source available for targeted iteration.”

The Proof Lab holds “all 11 checked-in scenarios, their JSON sources, named views, and validation receipts.” A worked case maps the public mco-org/mco repository at commit 9f1a1cf.

Grounded in the tt-a1i/archify README and the project’s Proof Lab.

Key features

• Typed JSON IR

  “Every renderer-backed mode has a schema and reproducible source.” The agent decides hierarchy, spacing, routes, and emphasis — “layout judgment over generic auto-layout” — and “shared automatic endpoints spread deterministically instead of piling arrows on one midpoint.”

• Atomic validation before delivery

  A same-directory candidate is rendered and checked; “only a passing artifact atomically replaces the target.” Failures leave the last known good output in place.

• Truthful interaction

  “Focus, upstream/downstream reach, exact routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology or claiming runtime impact.”

• Architecture Delta

  Compares validated Before / Delta / After snapshots “with exact added, removed, changed, moved, and rerouted facts” and a machine receipt. It “infers no impact, risk, or merge safety.”

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

• Source evidence, only when requested

  “Evidence-backed Architecture nodes mark themselves SRC n and open Git-verified files and line ranges pinned to one public commit; ordinary artifacts stay source-free.”

• Last-good live preview

  “An optional desktop loop watches one JSON file, refreshes only after the latest candidate passes every gate, and keeps the previous verified diagram visible when a save is incomplete or invalid.” It is loopback-only on a random 127.0.0.1 port.

• Export

  The Export menu copies PNG to the clipboard and downloads static or motion formats. Copy Share Card produces “a canonical 1200×630 image for a README, release, or social post”; after tracing a route or reach, Route and Reach Share Cards capture that exact reading. “Exports remain full-diagram and free of temporary viewer state.”

• A guide command

  Not sure which type fits? Ask the zero-dependency CLI.

  node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"

Setup

npx skills add tt-a1i/archify -g

For an explicit, non-interactive Claude Code install:

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

To try without installing:

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

Working with the repository directly:

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

In the viewer: ? opens the Diagram Guide, / finds and focuses a node, R probes a route, L compares roles, M opens the overview radar, P plays a guided story, F enters Presentation Stage, S cycles visual style, T toggles theme, E opens Export.

Notes

• It makes an update-check request — Archify “may GET the fixed stable manifest solely to show an optional reminder; it never downloads or installs updates.” The server “receives no version, Agent, project data, prompts, account/device ID, or ETag.” Set ARCHIFY_UPDATE_CHECK_DISABLED=1 to disable networking and reminder-state writes
• Development version runs ahead — the README lists v2.17.0-dev.1 as the current development version; check the CHANGELOG against the stable release
• Not a drawing editor — “Archify is not a general-purpose drawing editor or a Mermaid theme”
• What it deliberately does not infer — Architecture Delta “infers no impact, risk, or merge safety,” and the optional deployment-ownership profile “fails closed when authored owners, region placement, private database scope, or named crossings are missing; it is never implicit and does not inspect live infrastructure”
• Install count source — skills.sh (npx skills) telemetry, roughly 68,000 installs. It is not listed on claude.com/plugins
• Locale support is limited — meta.locale=en|zh-CN “localizes page title, Legend, states/errors, a11y, HTML/SVG lang—never authored content”
• License — MIT