oscardelgado02/artisan-uml-cli

A zero-dependency Node CLI (≥18) that keeps your code and a class diagram in sync —
built for **agentic workflows** (opencode, Claude Code, Codex). It scans your C#
into an editable UML diagram, lets you redesign the architecture **by hand** in the
editor, and turns those decisions back into code — while tracking who changed what,
human or agent.
> **Language support:** C# only, for now. More languages are planned.
Architecture decisions stay yours. The diagram is the meeting point: agents read it
(diagram.puml), the human edits it (diagram.html), and artuml reconciles both
sides. Any agentic workflow can drive this package from the terminal — no special
plugins required.
Why I built this
I'm Óscar Delgado, a software engineer. I like to plan the architecture first and keep
it visible as the codebase grows, that's why I built the
artisan-uml editor.
Agentic coding workflows changed how fast we build, but they brought a new problem:
agents happily create architecture on their own, new classes, new abstractions,
rewired dependencies, without any real control from the engineer, unless you write a
really specific prompt every time. The result is often code that works today and
drifts tomorrow, with no shared picture of the system.
This CLI is my answer for that side of the workflow. It turns your codebase into a
diagram you can *see*, gives you a fluid, visual space to make the architectural
decisions yourself, and then lets the agent do what it is great at, implementing them
fast. You keep the control and the overview; the agents keep the speed. Everyone
works from the same picture.
I released it as open source so that as many people as possible can use it. If it
helps you stay in the driver's seat of your next project, it was worth building.
Quick start
artuml not on PATH (common in agent shells and non-login terminals)? Run the
package instead — same commands: npx --yes artisan-uml-cli scan.
Then open **.artisan/diagram.html** — the editor as one self-contained file, no
server needed. Click **Connect file** once so your edits autosave to
.artisan/diagram.json. The bundled editor is the published
artisan-uml package, inlined into the file.
editor or serve?
Two ways to run the same editor:
| | artuml editor | artuml serve |
| --- | --- | --- |
| What runs | nothing — writes diagram.html, opens it | localhost HTTP server (:4173) |
| Autosave | browser File System Access API (**Connect file**, one click) | PUT /api/diagram over localhost |
| Extra | none | pending-changes API (GET /api/pending, POST /api/ack) |
| Browser | Chrome, Edge | any browser, incl. Firefox / Safari |
On Chrome/Edge, editor is all you need; serve is the fallback for browsers
without the file-handle API, or when you want the pending API.
With your coding agent
The main Artisan repo ships slash-command
packs (/artisan-scan, /artisan-diff, /artisan-implement, /artisan-architect,
/artisan-status) for opencode, Claude Code and Codex — its install.sh copies them
into your agent's command folder. Without them, any agent can still work from this
document: run artuml diff and read its markdown report, edit .artisan/diagram.json
and run artuml mark-ai.
The workflow
1. **artuml scan** — parses your C# into .artisan/diagram.json + a PlantUML mirror
agents read. Re-scan keeps your positions and notes.
2. **You redesign** in the editor: drag, rewire, rename, add classes, write notes.
3. **artuml diff** — compares the diagram against the last known state and prints a
markdown report for your agent: *rename these*, *scaffold these*, *notes to honor*.
Removals are never auto-deleted; the agent must ask.
4. **The agent implements** — refactors renames, scaffolds new code, writes bodies per