🎯 The Hallucination Problem
Ask an AI coding assistant to map your software architecture and you often get a chaotic web of hallucinated connections and overlapping layouts that don't exist in your codebase. 0:00
Archify resolves the spatial-reasoning problem — it translates natural-language descriptions and codebase context into mathematically verified interactive HTML diagrams. The key move: offload layout to a typed JSON intermediate representation, stripping the AI of visual-design responsibility.
Local-first: the rendering engine runs entirely on your machine — no cloud APIs — so the map is a secure, immutable record of your actual infrastructure, not a generalized AI guess.
🛠️ Install & Prerequisites
Check the environment first, then pick the right install path. 0:17
| Requirement | Detail |
|---|---|
| Node.js | v18 or later |
| npx | Available in terminal |
| Git | An authentic local repository (run from its root) |
| Chrome | Local install for viewport testing |
Two install paths: most setups install globally via the npx skills registry — assigning a CLI wrapper so agents like Claude Code or OpenCode discover the skill instantly. Cursor is different: its strict permission scopes require a specific command with non-interactive flags to silently inject the skill.
The Cursor trap: omit those silent-injection flags and the terminal throws interactive prompts — which an autonomous agent can't answer, so the setup stalls and fails. Don't cross the commands, or you pollute the environment and the agent can't resolve the skill.
📝 Prompt Boundaries
The prompt that keeps diagrams readable: explicit limits. 2:14
Limit the diagram to 8–12 core components and isolate a single primary path — this stops the agent from generating an unreadable maze.
The typed JSON IR: Archify forces the AI to output a rigid data tree — a typed JSON intermediate representation. The data contract strips the AI of visual-design duties; it only assigns semantic relationships, and the grid rejects any floating, illogical nodes. Check your file explorer: you should see a
bounded.json appear, confirming the agent is writing structured data, not hallucinating an image file.🔬 Doctor & Validate Workflow
Test the JSON before rendering — the trial-and-error loop. 3:08
Two commands:
doctor confirms the Node runtime and environment are healthy; validate mathematically inspects the JSON. Append the showcase-quality flag for the strictest artifact checks.Expect failures — don't fix coordinates manually. LLMs lack exact spatial reasoning, so coordinate collisions are a normal part of authoring. Feed the CLI's exact diagnostic receipt back to the AI, which outputs the spatial repairs. Loop until the CLI prints a clean receipt proving all nine artifact checks passed.
Sequence/workflow warning: never use the repository-root-evidence flag on sequence or workflow diagrams — it's exclusive to architecture mode and will trigger a fatal schema rejection.
📦 The Deliver Command
Compile the validated JSON into the finished HTML artifact. 4:16
Atomic delivery: the
deliver command requires a perfect validation score before writing to disk — so the resulting HTML is structurally flawless on arrival. Append --open to launch it in the browser immediately.Built-in keyboard controls: press
T to toggle light/dark theme; highlight a node and press R to probe the deterministic route (a visible trace along the target path); press E for the export menu (share cards). A mathematically sound, interactive asset ready for strict engineering review.💡 Key Takeaways
- AI can't do spatial layout — it hallucinates architecture diagrams; Archify constrains it to a typed JSON IR instead.
- Typed JSON IR strips visual-design duties — the AI only assigns semantic relationships; the grid rejects floating nodes.
- Verify with doctor + validate + showcase flag — nine artifact checks must pass before delivery.
- Feed the diagnostic receipt back, don't fix coordinates by hand — coordinate collisions are normal; the AI repairs its own layout.
- Cursor needs non-interactive flags — otherwise the setup stalls on interactive prompts.
- Never use repository-root-evidence on sequence/workflow diagrams — it's architecture-only and fatally rejects.
- Local-first means your topology never leaves the machine — secure, immutable record of real infrastructure.