Archify is an open-source agent skill that turns any codebase or system description into a polished, interactive architecture diagram — one self-contained HTML file, validated before it renders. It works across Claude Code, Cursor, Codex CLI, and OpenCode, installs with a single npx command, is model-agnostic, and sits at the top of GitHub Trending with more than 30,000 stars. If your team's diagrams go stale two weeks after they are drawn, this is the most direct fix available.
Why architecture diagrams are a bottleneck
Most architecture diagrams are wrong within a fortnight. Someone draws the happy path once, the code moves on, and the diagram quietly becomes a historical artifact nobody dares to update. Archify attacks the problem at the source: instead of rendering a hand-written description, the agent reads the actual repository, emits a typed JSON intermediate representation, and only then does Archify deterministically compile that IR into a diagram. The pipeline is fail-closed — if a schema, node layout, label, or edge check fails, you get the specific error and the allowed fix, not a pretty picture that lies about your system.
How it works: JSON IR, validation, then rendering
Archify splits "understanding" from "drawing" — the two things that usually go wrong together. The agent handles understanding: it reads your code, identifies components and relationships, and produces typed JSON following the Archify schema. Archify then applies deterministic rules: it validates the structure, checks layout, labels, and edge conflicts, and rejects anything that does not pass. A minimal slice of that IR looks like this:
{
"type": "architecture",
"theme": "dark",
"nodes": [
{ "id": "browser", "label": "Browser", "kind": "client" },
{ "id": "api", "label": "API Gateway", "kind": "service" },
{ "id": "cache", "label": "Redis Cache", "kind": "store" },
{ "id": "db", "label": "PostgreSQL", "kind": "store" }
],
"edges": [
{ "from": "browser", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "cache", "label": "read/write" },
{ "from": "api", "to": "db", "label": "fallback" }
]
}Only after the IR passes validation does Archify render a self-contained HTML/SVG file you can open in any browser: searchable nodes, traceable paths between any two nodes, upstream/downstream views, dark and light themes, and exports to PNG, SVG, WebM, and share cards. Five diagram types are supported — architecture, workflow, sequence, data flow, and lifecycle — plus three visual presets (Classic, Signal Flow, Blueprint). This verification-first philosophy mirrors what good agent tooling is moving toward generally, the same thinking behind zero-source hallucination checks in agent output.
Install in one command
Archify ships as a standard agent skill, so setup is one line:
npx skills add tt-a1i/archify -gIt drops into the skill directories your agent already reads: ~/.claude/skills for Claude Code, ~/.agents/skills for Codex CLI, and the Cursor skill manager for Cursor. No API keys, no cloud service, no server to run — everything renders locally.
Your first diagram: one prompt, one HTML file
Open a repository you need to understand, then ask the agent:
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.Bounding the request matters more than it looks. The "8–12 components, one primary path, trust boundaries" phrasing stops the agent from dumping every file into the picture — that is the difference between a diagram people read and a wallpaper. If you already know the shape of the system and just want a clean flow, describe it directly:
Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation -> Redis session lookup -> PostgreSQL fallback. Keep the cache-miss path secondary.Go further: deltas for PR review
The most underrated feature is the delta view. Archify can compare two validated snapshots and render the result as Before / Delta / After, marking exactly which nodes were added, removed, changed, moved, or rerouted. That turns the architecture diagram from a one-time artifact into something that participates in code review — run it on the base branch and the PR branch, then skim the diff instead of re-reading the whole system. If you are wiring agents into your delivery pipeline, pair it with the AI-Native SDLC Playbook for building agent-friendly CI and review flows, and read the durable agent state guide when your coding agents start running long-lived tasks that need checkpointing.
Practical tips
- Always ask for a bounded view. Unbounded "draw everything" prompts produce unreadable graphs.
- Commit the generated HTML to the repo and regenerate on merge — treat it as documentation that must stay current.
- Use the delta view for PR reviews; it highlights exactly what moved between two versions.
- Where supported, pin nodes to revision-verified source files so the diagram carries evidence instead of vibes.
Archify is not a runtime monitor and cannot prove the diagram matches production state — accuracy still depends on the code it reads, your prompt, and the agent's analysis. But as a tool to turn a cold, unfamiliar codebase into a navigable system map in minutes, it is the best open-source option right now.
FAQ
Q: Which coding agents does Archify support?
A: Claude Code, Cursor, Codex CLI, and OpenCode. It installs as a standard skill with npx skills add tt-a1i/archify and works with any model underneath.
Q: Is Archify just a prettier Mermaid?
A: No. Mermaid renders text you write; Archify validates a typed JSON IR before rendering, fails closed on bad input, and adds searchable interactivity plus Before/Delta/After comparisons for PR review.
Q: Does the generated diagram reflect the live system?
A: Not automatically. Archify is not a monitoring tool; correctness depends on the code it reads, your prompt, and the agent's analysis. Run it on current code and regenerate on merge.
Resources: Archify on GitHub · OpenAgentSkill registry
