# archify
archify is a free, MIT-licensed agent skill that reads your actual repository and compiles five
different kinds of system diagram — architecture, workflow, sequence, data flow and lifecycle — into
one self-contained HTML file you can open, click, search and send to someone. It installs with a
single command into the agent you already use, and the whole of its day-to-day interface is one
sentence typed in chat.
Everything below was run on 28 August 2026 before this was written. No command here is copied out of
a README without being executed first.
Why this is not just Mermaid again
You already have Mermaid. It is in GitHub, in your docs, probably in your editor. For a small
diagram you hand-write next to some code, it is still the right tool, and archify does not try to
take that job — it *accepts* pasted Mermaid as an input.
The difference is what happens after you write it. A Mermaid block is a picture nobody checks. It
says whatever you last typed, and it starts going stale the moment someone moves a service. There is
no mechanism by which it can disagree with your code.
archify puts a typed intermediate representation in the middle. Your agent writes a JSON spec,
archify runs machine checks over that spec, and it will not render an artifact that fails them.
Running one of the project's own examples:
node archify/bin/archify.mjs deliver architecture \
examples/rag-pipeline.architecture.json /tmp/rag.html --json
returned:
{ "ok": true,
"specification": { "bytes": 5286 },
"artifact": { "bytes": 714427 },
"validation": { "checksPassed": 9, "checkCount": 9,
"errors": 0, "warnings": 0,
"compositionStatus": "pass" } }
5,286 bytes of typed JSON in. A 714,427-byte interactive map out. Nine checks, zero warnings.
There is also a validate subcommand that runs those checks and writes nothing, which is the form
that belongs in CI.
Install it in about two minutes
1. Install the skill.
npx skills add tt-a1i/archify -g
That is the entire install. It reports where it went:
✓ ~/.agents/skills/archify
universal: GitHub Copilot, Amp, Antigravity, Antigravity CLI, Cline +12 more
symlinked: Claude Code
It runs a security check as it installs; on this machine it printed `Socket 0 alerts · Snyk Low
Risk. It creates exactly one new folder, ~/.agents/skills/archify` (6.8 MB), and one symlink at~/.claude/skills/archify. That was confirmed with a before-and-after diff of the skills directory
rather than taken on trust.
2. Ask for a map.
Use archify to map this repository's runtime architecture.
3. Open the file it gives you. That is the loop.
To remove it later, no rm -rf needed:
mv ~/.claude/skills/archify ~/.Trash/archify-symlink
mv ~/.agents/skills/archify ~/.Trash/archify
## The five maps answer five different questions
These are not five skins on one picture. Each one wants different things named in your prompt.
| Map | The question it answers | Name these in your prompt |
|---|---|---|
| Architecture | What are the pieces, and where are the boundaries? | scope, core components, the primary path |
| Workflow | What happens, in what order, and where does it branch? | participants, order, branches, exceptions |
| Sequence | Who called who, and what came back? | callers, callees, returns, timing |
| Data flow | Where does data enter, what touches it, where does it land? | sources, transforms, stores, boundaries |
| Lifecycle | What states can this end in, including the bad ones? | states, events, retry and cancellation paths |
The feature most people miss
archify can diff two maps:
node archify/bin/archify.mjs compare architecture base.json head.json delta.html --json
That renders Before / Delta / After with the exact added, removed, changed, moved and rerouted
facts. It is the difference between a diagram you generate once and forget, and one that turns an
architecture change into something a reviewer can actually look at in a pull request.
What it does not do
- You need Node.js. It is a Node renderer; that is not negotiable.
- The agent writes the spec, so the map is only as good as your agent's read of your repo.
archify guarantees the artifact is internally valid and checked. It cannot guarantee the agent
understood your code. Read the first map critically before you trust the fifth.
- The files are large. 714 KB for the example. That is the cost of one self-contained file that
works offline with no dependencies.
- It is documentation. It changes what your team can see. It will not find your bug.
- The project is sponsored (APINEBULA and EverMind are named in its README). Disclosed there,
disclosed here. It is MIT and the sponsorship gates nothing.
- It is not new. Created 15 April 2026. What is new is the adoption — roughly 4,260 stars in a
single day at the end of August, on a base of about 18,600.
Check any of that yourself:
gh api repos/tt-a1i/archify \
--jq '{stars:.stargazers_count, forks:.forks_count, licence:.license.spdx_id, created:.created_at}'
At the time of writing: 22,882 stars, 1,479 forks, MIT, created 2026-04-15 — and it moved by
seven stars between two polls a few minutes apart.
Get the kit
The kit is the install command, the five prompts that get you the five different maps, an honest page
on where this does not help, and map-this-repo.sh — a script that clones archify into a temp
directory, renders one of its own examples and prints the validation receipt, so you can find out
whether it works on your machine before you install anything globally.
Or comment MAP on the reel and I will send it to you.