Épure

Architecture diagrams that live in your repo and that Claude Code edits live while you watch.

   Try the editor online →

A diagram is just two small text files that diff cleanly in a pull request — D2 for the topology, a JSON sidecar for the layout. No SaaS, no account, nothing leaves your machine. Épure is built to be driven by Claude Code: it writes the files, you watch them render live, and you steer it in the conversation.

Use it with Claude Code

One-time setup (no install needed — npx fetches it from npm):

npx @theodo-group/epure skill install

Then, in any repo, just ask Claude Code:

"Diagram this service's architecture with epure."

It creates the diagram, opens it live in your browser, and refines it as you talk:

• Live — every edit Claude makes appears instantly in the editor.
• Yours to tweak — drag nodes or restyle by hand; changes are written back to the files (and into your next git diff).
• It can see the result — Claude renders a PNG to check its own work and discuss the visuals with you.

Use the editor on its own

Try it in your browser (nothing to install — edits stay in localStorage), or run it locally against a file pair:

npx @theodo-group/epure ./docs/diagrams/system.epr.d2

This prints a local URL and serves the editor against that pair, syncing your edits both ways. (It creates a starter diagram if the file doesn't exist yet.)

Use it as a library

The npm package also exposes the editor's internals as importable entry points (React 18 and 19 are both supported as peers):

// Headless pair to SVG/PNG, the editor's exact look; no browser, no DOM.
import { svg, png, model, source } from '@theodo-group/epure/render'
const image = await svg(d2, layoutJson)      // icons inlined by default
const pair = source(await readFile('x.png')) // { d2, layout } from any Épure PNG

// The bundled icon catalog (~9.4k icons) and its zero-dependency search.
import { search, icon, url } from '@theodo-group/epure/icons'

// The diagram as a React component (SSR-clean), plus the parts it is made of.
import { Diagram } from '@theodo-group/epure/react'
const m = await model(d2, layoutJson)
return <Diagram model={m} />

Embed the editor in your page

@theodo-group/epure/bridge puts the hosted editor (GitHub Pages or your own deploy) in an iframe and hands every edit back to your page:

import { embed } from '@theodo-group/epure/bridge'

const session = embed(iframe, {
  app: 'https://theodo-group.github.io/epure/',
  doc: 'system',                    // the name in the editor's tab bar
  files: { d2, layout },            // layout: null when no sidecar exists yet
  onChange: (files) => save(files), // or read session.files() on close
})
// later: session.close()

Commands

Every command is npx @theodo-group/epure <command>:

Command	What it does
<file>	Open the live editor for a diagram pair.
new <file>	Create a new pair (won't overwrite an existing one).
export <file> -o out.png	Render a PNG, fit to the diagram — no browser.
source <file.png>	Recover the editable pair from any Épure-rendered PNG (-o <name> writes it).
icons <query>	Search the bundled icon catalog from the terminal.
validate <file>	Check the pair for errors (non-zero exit on problems).
fmt <file>	Tidy the layout JSON so diffs stay small.
skill install	Install the Claude Code skill into ~/.claude/skills (add --local to install into the current repo's .claude/skills so it's committed and shared with the team).

Typing that a lot? Install once — npm i -g @theodo-group/epure — and use the shorter epure <command>.

Keep the @theodo-group/ scope: the bare epure package on npm is an unrelated, long-abandoned project, so npx epure won't run this tool.

The files

A diagram is a pair sharing a basename, both committed to your repo:

• <name>.epr.d2 — the topology: nodes, shapes, edges, labels, groups.
• <name>.epr.layout.json — the visuals: positions, sizes, colors, icons.

# system.epr.d2
api: API { shape: rectangle }
db: Postgres { shape: cylinder }
api -> db: "writes"

You rarely write these by hand — Claude Code does. See fixtures/system.epr.* for a complete example, and pick from thousands of cloud/infra/brand logos — plus a badge for every standard file type (.js, .py, .pdf, .docx, .zip, …) — via the Icon control in the editor.

Keeping diagrams in a repo? Add this to its CLAUDE.md so Claude Code uses them:

## Architecture diagrams (Épure)
Diagrams live as `<name>.epr.d2` + `<name>.epr.layout.json` under `docs/diagrams/`.
Run `npx @theodo-group/epure <file>.epr.d2 &` to open the live editor, edit
the pair, and `npx @theodo-group/epure export <file>.epr.d2 -o /tmp/x.png`
to see the result.

Contributing

pnpm install && pnpm dev      # the editor against a fixture
pnpm test                     # vitest

Requires Node 20+. See RELEASING.md for publishing and the Pages demo.

License

MIT — see LICENSE.