pi-excalidraw

pi-excalidraw

pi-excalidraw gives pi a locally hosted Excalidraw canvas plus AI-callable tools for drawing, layout, screenshots, persistence, templates, and mixed-diagram composition.

It is built for a practical local loop: pi starts the Excalidraw runtime, you keep the canvas open in a browser, and the model uses tool calls plus screenshots to create and refine diagrams on that live whiteboard.

[!IMPORTANT] pi-excalidraw is a local, browser-connected workflow. Canvas interaction, viewport control, screenshot capture, and image export require a connected browser tab or pane. This package does not provide a hosted Excalidraw service or a fully headless drawing runtime.

What ships today

The published package includes these validated capabilities:

• Start and manage a local Excalidraw canvas from pi
• Create, inspect, update, delete, clear, export, and screenshot canvas elements
• Generate higher-level diagram structures with nodes, connected flows, titled panels, and wrapper helpers
• Apply deterministic layout polish with horizontal, vertical, and centered-flow modes
• Save and reload project-local diagrams under .pi/excalidraw-diagrams/
• Save and apply reusable templates under .pi/excalidraw-templates/
• Use improved sizing, spacing, composition helpers, and final layout polish from the shipped Phase 10–12 work

Not shipped yet:

• Mermaid conversion
• Hosted/cloud canvas workflows
• A separate collaboration backend beyond the local Excalidraw canvas flow

Installation

Install from npm

Install the package into the project where you run pi:

npm install pi-excalidraw

Then start pi in that project. If pi is already running, use /reload so it re-discovers installed packages and extensions.

Install from git

pi install git:github.com/coctostan/pi-excalidraw

Install from a local checkout

pi install /absolute/path/to/pi-excalidraw

Requirements

• Node.js >=20
• A local browser you can keep connected to the reported Excalidraw URL

Quick start

• Start pi in the project where pi-excalidraw is installed.
• Run /excalidraw to start the local Excalidraw runtime.
• Open the reported URL in a browser and keep that canvas connected.
• Ask pi to create or modify a diagram.
• Use focus and screenshot steps to visually validate the result.

Example requests:

• “Open Excalidraw and sketch a simple system diagram.”
• “Create three connected nodes for API → worker → database, then lay them out horizontally.”
• “Wrap these nodes in a titled panel called Ingestion Pipeline.”
• “Save this as a reusable template called architecture-review.”
• “Focus the canvas, capture a screenshot, and tell me if the labels are readable.”

Usage

Common workflow

A typical session looks like this:

• Open the live canvas with /excalidraw
• Ask pi to create or modify diagram content
• Ask pi to polish layout
• Ask pi to focus the canvas and capture a screenshot
• Iterate until the diagram looks right
• Save the result as a diagram or template if you want to resume later

High-level helpers

The package exposes higher-level tool workflows for:

• polished single nodes and labeled boxes
• connected-node diagrams
• titled composition panels
• wrapping existing content in titled panels
• deterministic diagram layout and polish
• viewport focusing and screenshot capture
• diagram save/list/load
• template save/list/apply

Persistence workflow

For project-specific work, save the current scene as a diagram bundle and reload it later:

• diagrams are stored under .pi/excalidraw-diagrams/
• templates are stored under .pi/excalidraw-templates/

This keeps Excalidraw work resumable across sessions without adding remote persistence infrastructure.

Current package structure

This repository uses the repo root as the canonical pi package entrypoint:

src/index.ts                          # canonical extension entrypoint declared in package.json
.pi/extensions/pi-excalidraw/index.ts # thin local development shim for /reload while working in this repo
vendor/mcp_excalidraw/                # vendored Excalidraw runtime used by the local server workflow
scripts/smoke-test.mjs                # package smoke test
assets/readme/                        # package/readme graphics

Validation

From the repository root:

npm install
npm run check

npm run check runs:

• npm run typecheck
• npm run smoke-test
• npm pack --dry-run

Local development with /reload

If you are developing inside this repository, you usually do not need to reinstall the package after every edit.

• Open pi with this repository as the current project.
• Edit src/index.ts or related files.
• Run /reload.

Why that works:

• pi discovers .pi/extensions/pi-excalidraw/index.ts in this repository
• that shim re-exports the canonical implementation from src/index.ts
• /reload refreshes the extension in the current project session

Runtime constraints and design notes

Connected browser required

The live Excalidraw frontend must be open in a browser for the canvas to exist. Screenshot, viewport, and export workflows depend on that connected client.

Vendored runtime by design

The repository vendors the Excalidraw runtime under vendor/mcp_excalidraw/ because the published upstream package did not ship the runnable frontend/runtime assets needed for this extension's local server workflow.

Scope stays intentionally tight

pi-excalidraw is focused on reliable local diagramming workflows for pi. It does not currently try to be a hosted service, a generic docs site, or a Mermaid conversion layer.

Repository and support

• Repository: https://github.com/coctostan/pi-excalidraw
• Homepage: https://github.com/coctostan/pi-excalidraw#readme
• Issues: https://github.com/coctostan/pi-excalidraw/issues

If you want to inspect the package before installing, start with src/index.ts, package.json, and the vendored runtime layout under vendor/mcp_excalidraw/.