Mirofy

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

This is the whole product: one HTML file, open in a browser. Every colour in it is the system’s own vocabulary — backend, database, cloud, security, message bus, external — and nothing else. Colour never marks where an arrow goes, only what a thing is .

Open this exact file ↗ — click any node for its evidence, trace what reaches it, search it, present it.

---

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:

Every box is the same colour here, and that is the point. All twelve of these are the same thing — a package, derived from a manifest — so there is nothing for colour to say, and it says nothing. The picture at the top is colourful because that system genuinely has six kinds in it. A tool that tinted these boxes to look livelier would be inventing a distinction it had not found.

Open the live one ↗ — click any node for the file, line range and commit behind it.

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 sends the diagram and the intermediates there instead, so nothing lands in your repository; without it the intermediates go to /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.

Or call it from your own code

mirofy-cli/api is the same pipeline as a library — no argv, no process.exit, and no stderr to parse:

import { render, validate, map } from 'mirofy-cli/api';

const html = await render('architecture', diagram); // one HTML string const { ok, diagnostics } = await validate('architecture', diagram); const { html, drawn, coveragePath } = await map('.'); // the whole pipeline

A rejected document throws a MirofyRenderError carrying .diagnostics — the renderer's own structured report, each entry with a code, a subject, the evidence behind it and the fixes it supports. validate returns that report instead of throwing, because "this document is invalid" is an answer, and checking a hundred documents should not need a hundred try/catch blocks.

map needs a git repository: every fact is pinned to a revision, so a directory with no commit has nothing for the evidence to cite, and it says so rather than failing further down.

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 17 gaps it could not read; derives 19 components and 21 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

<img src="assets/evidence.svg" alt="One drawn edge, opened: the passport shows the relation depends-on, provenance statically-derived, the source line render-workfl