excalidraw

<div align="center">

✏️ Excalidraw Diagrams for Claude Code

Ask for a diagram. Get hand-drawn .excalidraw files that actually explain things.

Claude writes the JSON, renders it locally, looks at the image, fixes what's wrong — and only then shows you. No browser, no server, no canvas app. Just files.

</div>

---

!Example: a full ML pipeline documented as linked visual notes

<p align="center"><em>One conversation → a multi-panel visual doc. Opens and stays editable on <a href="https://excalidraw.com">excalidraw.com</a>.</em></p>

Why it's different

• 🔁 It reviews its own work. Every diagram is rendered to PNG (locally, ~1.4s, pure Python — no Chromium) and visually audited against a 12-point checklist: clipped text, overlaps, floating arrows, crossing spaghetti, missing focal point. Found → fixed → re-rendered. You never see pass 1.
• 🎨 Visual-first methodology. Diagrams argue, they don't display. Structure carries the meaning — if you deleted every word, the picture should still teach. Uniform boxes-in-a-grid is treated as a bug. Text is seasoning, never structure.
• 🧠 Any subject. Codebases and architectures, research papers, the decision you discussed five messages ago, business processes, ER data models, incident timelines, abstract concepts.
• 🎚️ A depth dial. Walkthrough (numbered reading path, example values flowing through, legends) · balanced · clean reference. It asks when it matters, infers when it's obvious.
• 🗂️ Big systems decompose into linked C4-style views — overview + per-component files — instead of one unreadable mega-canvas.
• 🔗 Share in one command — encrypted upload straight to an excalidraw.com link.

<p align="center"> <img src="assets/example-detail.png" width="520" alt="Detail: concepts drawn, not captioned"> </p> <p align="center"><em>Detail from the example above — concepts get drawn, not captioned.</em></p>

Install

As a plugin (recommended — works in every repo, auto-updates):

/plugin marketplace add sidfeels/excalidraw-diagrams
/plugin install excalidraw@excalidraw-diagrams

Or as a plain skill (this machine, all projects):

git clone https://github.com/sidfeels/excalidraw-diagrams
cp -r excalidraw-diagrams/skills/excalidraw ~/.claude/skills/

Requirements (for the local render-and-review loop):

| | | |---|---| | uv | runs the bundled renderer, zero setup | | cairo | brew install cairo · apt-get install libcairo2-dev |

No uv/cairo? Everything still works — Claude authors valid .excalidraw files and lints their geometry; you only lose the visual self-review pass.

Use it

Just ask:

• "Diagram the request flow through our gateway, auth service, and database."
• "Read this paper and turn the method into a visual explainer." — walkthrough depth, numbered path
• "Draw the architecture decision we just made, options and all." — mined from your chat
• "ER diagram for users, orders, payments — crow's-foot, clean reference style."
• "Map the incident timeline from this postmortem doc."

Diagrams land in excalidraw/ in your project — each .excalidraw with its rendered .png beside it (a bundled hook re-renders on every edit).

How it works

understand the subject  →  plan (one flow axis, one hero, ≤3 hues)
        →  author terse JSON  →  geometric lint  →  render PNG
        →  Claude READS the image  →  audit  →  fix  →  re-render
        →  deliver  (your chat feedback keeps iterating)

The skill ships a single helper CLI (excal.py) that handles the error-prone geometry deterministically:

| Command | Does | |---|---| | render | .excalidraw → PNG, hand-drawn fidelity, ~1.4s | | check | lints geometry: overlaps, text overflow, dangling arrows, broken refs | | connect | edge-to-edge arrows with proper two-way bindings (straight / elbow / labeled) | | textbox | correctly centered bound text in any shape | | share | end-to-end-encrypted upload → excalidraw.com/#json=… link |

Plus ~1,000 lines of distilled diagramming methodology: layout ranking, semantic color discipline, a pattern library (fan-outs, offset stacks, timelines, evidence panels), arrow routing rules, and decomposition protocols. Read skills/excalidraw/SKILL.md — it's the product.

Troubleshooting

• pycairo build fails → install system cairo first (see Requirements), then retry. Python 3.12 is pinned for wheel availability.
• Renders look slightly different from excalidraw.com → the local preview is for layout QA; fonts and fill textures are approximated. The .excalidraw file is always the source of truth.
• No grid/fonts in your editor → drag the .excalidraw file onto excalidraw.com — everything round-trips.

License

MIT