mirofy

Diagrams of your system that cite their sources — and say what they could not see.

---

What it is

Point Mirofy at a repository. It reads the code into an evidence graph, builds a model from that graph, and compiles the model into one HTML file you can open, search, share and check.

Every relationship it draws can answer one question: what is the evidence for this? Each carries the file, the line range and the commit it came from. Where nothing is known, the diagram says so instead of filling the gap.

Run it against this repository and you get this — not a mock-up, and not drawn by hand:

Install

Nothing to install — one command, and a diagram opens:

npx mirofy-cli map .    # YOUR repository, mapped, in one command
npx mirofy-cli demo     # a finished artifact, to see what this produces
npx mirofy-cli init     # a starter document of your own to edit
npx mirofy-cli render architecture architecture.json

Give it to your agent instead — one line, and the skill installs for Claude Code, Cursor, Gemini CLI, Amp and a dozen others:

npx skills add Hasan-Laraib/Mirofy

Then ask: map this repository's architecture. Your agent reads SKILL.md and drives the same CLI.

In Claude Code, the plugin carries both the skill and the MCP server:

/plugin marketplace add Hasan-Laraib/Mirofy
/plugin install mirofy@mirofy

Every one of these routes is the same package. The agent never draws the diagram — it runs the CLI you would have run, which is why nothing it reports can drift from what the CLI reports.

map runs the whole pipeline in the directory you point it at — scan, model, compile, layout, render — and writes architecture.html next to your code. map --out <dir> sends the diagram and the intermediates there instead, so nothing lands in your repository; without it the intermediates go to <target>/scan. Naming an output path still wins over both. It works on a repository that declares no workspaces: where there are no packages to draw, it models the source directories and the imports between them.

What it reads

JavaScript and TypeScript imports · Python imports · Go imports · Java imports · Rust imports · Kotlin imports · package.json workspaces · Express and Next routes · docker-compose.

That is the whole list, and the list is the point. Everything else is reported, not skipped: coverage.md names every file no adapter opened, grouped by type, and map says so on its way out when the unread files outnumber the read ones. Point it at a Ruby repository and you get an honest empty answer naming every unread .rb file — not a confident small one drawn from the two JavaScript files in an examples/ folder.

Python resolves by file existence, not by convention: relative imports against the importing file's directory, absolute ones against the repository root and any directory that actually holds a package. A specifier that matches two source roots is a gap naming both, because which one wins depends on sys.path, which is configuration and not in the source.

Go resolves against the module path go.mod declares, and decides the standard library the way the toolchain does — a first path segment containing a dot is a domain, and a domain means a module fetched from somewhere. Java builds its index from the package statements files declare, not from directory layout: Maven convention puts com.acme.store under src/main/java/com/acme/store and convention is not always, but the declaration is what the compiler reads.

Rust peels a use from the right until a real file appears, because use crate::a::b::C does not say which of a, b or C is the file. It reads the crate name and the source root from Cargo.toml — including a declared [lib] path, since src/ is only the default — and knows that Cargo compiles every direct child of tests, benches and examples as its own crate.

Kotlin reads its type index from the declarations themselves — class, interface, object, typealias and fun interface among them — rather than from file names, because a Kotlin file need not be named after the type it holds and may declare several. It shares that index with Java: the two compile to one namespace and import each other freely, so an index of one extension reports a real edge to the other as a missing type.

In every one of them, an import that names something inside this repository which is not there is a gap — never a dependency on a published copy of yourself.

npx mirofy-cli guide "show an API request with a cache miss" picks the diagram type for you if you are not sure which one you want.

As a CLI you keep — npm install -g mirofy-cli. The command it installs is mirofy; the package carries the -cli suffix because npm refused the bare name as too close to the existing minify.

From source — no install at all, because there is nothing to install:

git clone https://github.com/Hasan-Laraib/Mirofy.git
node Mirofy/packages/core/bin/mirofy.mjs demo

That works on a bare checkout with no npm install, because every package here has zero runtime dependencies.

As an agent skill — build the bundle and copy it where your agent looks:

git clone https://github.com/Hasan-Laraib/Mirofy.git
cd Mirofy && npm install && npm run build:skill

cp -r dist/mirofy ~/.claude/skills/      # Claude Code
cp -r dist/mirofy ~/.agents/skills/      # Codex CLI, opencode

Then ask: Use mirofy to map this repository's runtime architecture.

The bundle is 2.8 MB and named for the skill inside it — copying packages/core instead installs a skill called core that says in its own frontmatter it is called mirofy, and drags the test suite along with it. Before writing the bundle, build:skill copies it somewhere with no repository around it and renders a diagram: a bundle that only works inside its own checkout is not a bundle.

Nothing is downloaded at runtime and nothing phones home — there is no update check, because a tool that reaches the network to tell you about itself is a tool that reaches the network.

The pipeline, one step at a time

mirofy map is these five steps in order. If you only want the intermediates, mirofy map . out.html --out ./scan writes every one of them — the evidence graph, the model, the view and the positioned document — into that directory.

To run a step on its own, or point one somewhere else, you need a checkout; these are the repository's own npm scripts, not commands the installed package exposes:

npm run scan                    # repository  → evidence graph
npm run model -- --from-graph --graph scan/evidence-graph.json
npm run compile                 # model       → a bounded view
npm run layout                  # view        → positioned document
node packages/core/bin/mirofy.mjs render architecture scan/diagram.json out.html --repo-root .

Against this repository it records 1,227 facts across 223 files, with 16 gaps it could not read; derives 18 components and 20 relationships — every one citing the file and line it came from — and draws twelve, recording what it left out and why.

Those figures are checked, not remembered — see the numbers on this page below.

Those commands reproduce the diagram at the top of this page. It is checked in under assets/ as documentation; the interactive artifacts are built, never stored.

No repository? Author a JSON document, or convert a Mermaid diagram:

node packages/core/bin/mirofy.mjs import mermaid design.mmd
node packages/core/bin/mirofy.mjs render architecture design.json out.html
node packages/core/bin/mirofy.mjs validate architecture design.json --json

What you get

Three claims about the pictures below, each with the thing that keeps it honest.

The viewer, actually being used

Not mock-ups. Every frame below is a capture of the shipped viewer, driven through real clicks by scripts/build-screenshots.mjs — which fails rather than reuse an old picture if a control is renamed or a panel stops opening, and refuses to save a shot of a feature that did nothing.

---

What it does that a diagram tool doesn't

It refuses to guess

A file the scanner cannot parse becomes a recorded gap, never a silent omission. Every fact is labelled with one of six provenance classes, so source-backed and inferred never look alike.

The same rule holds where a decision has to be made that evidence cannot settle. A derived component's kind is package — the scanner knows a manifest exists, not whether something is a "backend". 784 imports of Node builtins are counted and named, not drawn and not dropped in silence. In Python a computed importlib.import_module(name) is a gap with its line, and docstrings are blanked before parsing — a docstring full of example imports would otherwise become edges the code does not have, cited to prose. A citation with no pinned commit to verify against is discarded rather than shown, because a citation nobody can check is worse than none — map reads the commit from your origin remote, or takes --repo-url and --revision when there is no remote to read.

A passport lists at most three sources, because forty-three links is not a passport. It says “Showing 3 of 43 cited sources” when it does, so a bound on the drawing is never mistaken for a claim about the evidence.

It answers questions about your system

mirofy explain callers api     # what points at api
mirofy explain impact api      # what is downstream of it
mirofy explain find payment    # id, label, kind or metadata match
mirofy explain gaps            # what the scan could not read

Every answer names the unread files that could change it. "Nothing calls PaymentService" is useful if the scanner read everything and reckless if six files failed to parse — so an empty result means not found, never does not exist.

impact answers as reachability and refuses to be more. What is connected is a fact about the graph; whether a change breaks it is a judgement about a running system, and Mirofy has no evidence for that.

Your agent can ask too

The same queries over MCP — 11 tools, the same engine, not a second implementation that could disagree with the CLI. assert and timeline are there too, because "is this change allowed" and "what has been moving here" are questions an agent asks while editing, and one that has to shell out to ask them will not ask at all:

{ "mcpServers": { "mirofy": { "command": "npx", "args": ["-y", "mirofy-cli", "mcp"] } } }

Point any MCP client at that. It reads ./scan — whatever map --out ./scan last wrote — relative to the directory the client starts it in; --model and --graph override. No clone, and nothing to install first.

The incompleteness warning is in the prose an agent reads, not only the JSON. Most clients feed the text to the model and drop the rest.

It checks architecture rules — with three outcomes, not two

mirofy assert     # reads architecture-rules.json

pass, fail, and unproven. A rule that found no violation over a scan with unread files has not been shown to hold, so it never counts as passing. Turning a gap into a green check is the one failure this project exists to avoid.

Some gaps are permanent — a dynamic import whose base path is a variable cannot be resolved without guessing. Those can be acknowledged, one path at a time, quoting the gap's reason and carrying a written argument. An acknowledgement written for a dynamic import stops applying the day that file fails to parse instead. And a rule that passes on the strength of one says so:

[ok  ] no-cycles — No violation. 8 unread file(s) are acknowledged as unable
       to hide one; this rests on that judgement, not on a complete scan.

2 passed, 0 failed, 0 unproven of 2
2 of those rule(s) rest on acknowledged gaps, not on evidence.

It tells you what is moving

mirofy timeline                                # cited-file churn, newest first
mirofy drift --base a.json --head b.json       # what two scans say differently

Drift reports changed facts and nothing else — no score, no risk label, no merge recommendation. It runs on every pull request and can never fail one.

---

The number we would rather not publish

A benchmark asks one question: hand a model a written brief, and how often does the diagram it writes come out usable on the first attempt?

Right now, over eight briefs authored by Claude Code: 2 of 8.

node scripts/benchmark.mjs --author "<your command>" --model "<id>" --keep benchmarks/corpus/mine
node scripts/benchmark.mjs --replay benchmarks/corpus/mine

That is not a good number and it is the real one. Three things make it worth printing anyway.

Usable means clean, not accepted. A warning is the diagram telling you it needs a second look, which is exactly what a first-pass rate is supposed to exclude. Two more documents in that set validate with zero errors and are still not counted.

It is measured against a saved corpus, not a fresh one. --keep stores what the model produced; --replay re-runs the tool over those exact documents without calling the model again. Without that split, every re-run changes both the documents and the tool, and any movement can be attributed to either — which is why the rate sat at zero for weeks without anyone being able to say what was wrong. A replay cannot even claim a different author: the model is read from the saved manifest, and --model is refused if it disagrees.

It moves for reasons you can name. The last change to the layout engine took the same eight documents from 0 of 8 to 2 of 8, and total composition errors from 121 to 34, because a diagnostic that said "shorten the label or widen size" was asking an author to rename part of their system to fit a box the renderer had picked. The renderer now widens the box.

If you compare this to a number published elsewhere, check what was measured. A rate for an agent that can call a validator and repair its own output, reviewed by a person at the end, is a different measurement from a blind single-shot model — not a worse one, a different one. Ours is the second kind.

---

Inside the artifact

• Node Finder, Semantic Lens, Semantic Radar — search, filter and overview a diagram too large to read at once
• Route Probe — resolve a directed path and see it traced, hop by hop
• Semantic Passport — click a node for its type, tags and cited evidence, with a Verified Source Beacon on anything backed by a pinned commit
• Your code, drawn apart from everyone else’s — a module you wrote is solid, a third-party package is dashed. Not a colour: the colour-blind-safe preset already spends all seven of its hues on the seven semantic roles, so an eighth would be a distinction only some readers could see
• Guided views, presentation mode, motion governor, and ?embed=1
• Three exports, copied straight to the clipboard:
  • Export → Share Card — a 1200×630 PNG in the current theme and preset
  • Export → Route Share Card — the exact route a Route Probe resolved
  • Export → Reach Share Card — the set a reachability query returned

A card shows what the reader actually did. None of them claim validation, and none are produced from a query that returned nothing.

npm run gallery      # every type in every preset → preview/index.html
npm run build:site   # the same, plus this repo's self-model → site/

The second is what CI publishes to hasan-laraib.github.io/Mirofy on every commit. Nothing is committed: the site is built from the code at the commit it describes, so it cannot go on quietly describing an older one.

Taking it elsewhere

The interactive file is ~720 KB and earns it. None of that survives a README, a pull request or a Notion page, though — all of them strip scripts. So:

# 19 KB standalone SVG: no scripts, no stylesheet needed
node packages/core/bin/mirofy.mjs render architecture in.json out.svg --format svg-static

# or open it in an editor you already own — from a checkout; the export
# package is not bundled into the published CLI
npm run export -- drawio     architecture in.json
npm run export -- excalidraw architecture in.json