Obsidian excalidraw

obsidian-excalidraw

Draw into live Obsidian Excalidraw files by chatting, via obsidian CLI + ExcalidrawAutomate (ea) API.

Prerequisite: Obsidian running with the Excalidraw plugin loaded.

Principles

1. ea API is source of truth. No direct JSON edits, no standalone renderer — everything happens in the open vault.
2. Visual verification is mandatory. Ship nothing you haven't inspected element-by-element.
3. Archetypes, palettes, and sizes are starting scaffolds — not a cage. Hybridize or invent when the material calls for it. Make it tasteful; the rules below are the floor, not the ceiling.

Hard Rules

Deviation produces silent failures.

1. Never write .excalidraw JSON directly for authoring — use the ea API. (Clobbers live view, races with Obsidian's save, loses undo.)
2. Target drawings by path, not basename — e.g. Excalidraw/foo.excalidraw.md.
3. Always call await ea.addElementsToView(false, true) with save=true. (Otherwise: renders but doesn't persist; next Cmd+Z wipes it.)
4. Reset ea.style between differently-styled elements. ea.style is shared mutable state — any property you ever set per-element must also be in the reset helper, or it sticks. (See LESSONS: strokeStyle bleed.)
5. Visually verify before declaring done. Read the sidecar PNG at <drawing-path>.excalidraw.png (plugin writes it on save); fall back to obsidian dev:screenshot /tmp/check.png only if no sidecar. Inspect element-by-element, not overall vibe — check each for: alignment (grid-snapped, same-axis elements share coords), overflow (text fits container; use Virgil width formula), style bleed (no unintended dashed/colored leaks), font-size minimums (26pt+ for secondary labels on YouTube), container fit (no wrap past text-height cap). Cap at 3 verify-fix cycles — if issues remain after 3, flag to the user rather than looping.
6. For any drawing above ~5 primitives, propose plan in plain English first, wait for confirmation, then execute. Skip for SKETCH.
7. Before invoking any Downloaded script, check its classification in SCRIPTS.md. Selection-only scripts fail silently without a selection (use Pattern 2 to select first). Hard-interactive scripts (in_scope: no) block on a modal and return false success — ask the user to run them manually or fall back to ea primitives.

Archetype menu

Pick the archetype whose triggers match. Default: DIAGRAM. Archetypes are scaffolds, not a cage — hybridize freely, or compose primitives directly when nothing fits. The ea API is complete; don't wait for permission to invent.

Archetype	Triggers	Load
DIAGRAM	diagram, architecture, system, flow, pipeline	references/archetypes/diagram.md
LAYERED-ARCHITECTURE	enterprise architecture, layered, n-tier, trust zone, service architecture, system topology, tenant architecture, cloud architecture	references/archetypes/layered-architecture.md
METAPHOR	metaphor, visualize X as Y, concept art, thumbnail	references/archetypes/metaphor.md
CHART	chart, graph, plot, data viz, histogram	references/archetypes/chart.md
MINDMAP	mindmap, brainstorm, radial, concept map	references/archetypes/mindmap.md
COMPARISON	vs, compare, before/after	references/archetypes/comparison.md
FRAMEWORK	2x2, quadrant, matrix, decision tree	references/archetypes/framework.md
SKETCH	sketch, rough, just, quick, draft	references/archetypes/sketch.md
ANNOTATION	annotate, mark up, add to, label	references/archetypes/annotation.md

Commands cheat sheet

Simple ops use obsidian CLI directly. (For broader CLI usage, see obsidian-cli skill.)

Purpose	Command
Create new drawing at known path + draw into it	Pattern 0 in references/eval-templates.md
Run a JS payload >2KB	scripts/obsidian-draw <file.js> [--target <path> --create]
Read saved drawing PNG (preferred)	Read <drawing-path>.excalidraw.png
Screenshot active view (fallback)	obsidian dev:screenshot /tmp/check.png
Run Downloaded script (no selection needed)	obsidian command id="obsidian-excalidraw-plugin:Downloaded/<Script Name>"
List drawings in vault	obsidian files folder=Excalidraw ext=md
Get active Excalidraw file path	obsidian eval code="app.workspace.getLeavesOfType('excalidraw').map(l => l.view.file?.path)" — not activeLeaf (that's often the terminal pane)

For inline JS, use an obsidian eval block — see references/eval-templates.md. For anything over a couple of KB, write the JS to a file and run it via scripts/obsidian-draw to skip the shell-quoting + readFileSync boilerplate. Don't use excalidraw-autocreate for scripted flows; Pattern 0 replaces it.

Eval patterns

Three copy-adapt templates in references/eval-templates.md:

1. Draw primitives — add new elements via ea.add*. Most common.
2. Select + invoke script — programmatic selection then run a script.
3. Query state — read current elements.

Load the template file when writing an eval block. Don't write one from memory.

Progressive disclosure

When to load	File
Start of every session	LESSONS.md
Before writing any ea.* code	references/EA_API.md
Before invoking any Downloaded script	references/SCRIPTS.md
Before writing any obsidian eval block	references/eval-templates.md
Before any drawing with 3+ aligned elements	references/layout-helpers.js (require + use; eliminates coordinate math + style-reset boilerplate)
Archetype matching user's triggers	references/archetypes/<name>.md
User's idea maps cleanly to a flywheel / 3-step / 3-col comparison / 4-frame storyboard / grid backdrop	references/templates.md
Adding cloud-service icons (Azure / AWS / etc.) to a diagram	references/icons/manifest.json (logical name → file path; use H.serviceIcon(name, {x,y,size}) from layout-helpers)
User wants PNG/SVG output	references/export.md

Scope boundaries

In scope: create/modify drawings in open vault; 21 of 33 Downloaded scripts; PNG/SVG export; screenshot-verify loop.

Out of scope: offline .excalidraw JSON (that's excalidraw-diagram); cross-vault; multiplayer; mouse-event-reactive; plugin install/config; 12 hard-interactive scripts (see SCRIPTS.md).