Diagram with your agent. Stay in control.
Use Claude Code or Codex to edit an existing Excalidraw diagram. Review what changed, keep drawing in the same workspace, and export a native file you can keep editing. Your original file and unrelated work stay intact.
Watch the launch film · 38 seconds → · Explore the toolkit · Get started
Real product captures: agent edits, before/after review, manual drawing, export, and reopen. Camera motion and transitions are added for pacing.
Extend this architecture diagram with the MCP interface in
src/scoped-mcp.js. Show where agent requests enter and how verified images come back. Preserve the existing pipeline, layout, and notes.
The agent inspects existing elements, applies supported edits by ID, and returns
an edited .excalidraw copy with before/after PNGs and a change receipt.
This real Codex/MCP edit extends a nine-stage diagram of this repository into an eleven-stage overview. The blue additions show the existing MCP interface; the original pipeline and annotations stay in place. Try the original diagram, open the edited result, or read the task and source references.
Implemented on main. The npm latest release is still 0.1.0; it does not include these workflows. Version 0.2.0 is not published yet. Use the source setup below.
| Task | What the toolkit provides |
|---|---|
| Recolor or rename a component | Scoped style edits and measured bound-label updates. |
| Revise a flow | Move supported shapes and reanchor bound arrows; add nodes/connections; remove or detach explicit dependencies. |
| Explain a code change | Source-linked before/after diagrams at article, slide, or canvas dimensions. |
| Update a diagram after code changes | A staged refresh that preserves manual overrides and identifies conflicts. |
| Run from CI | Explicit source scope, execution budget, retained artifacts, and stale-event checks. |
| Publish a PR update | An opt-in managed comment that reconciles retries and checks the current PR head. |
Your existing coding agent supplies the reasoning. The toolkit owns supported native edits, preservation checks, rendering, and retained results; it adds no extra model service.
Use Node.js 24.15+ in the 24.x line (or Node 26+), Git, and a POSIX shell with tar. The build uses npm 12.0.2:
git clone https://github.com/edwingao28/excalidraw-toolkit.git
cd excalidraw-toolkit
npx --yes npm@12.0.2 ci
npx --yes npm@12.0.2 run build
TOOLKIT_CLI="$PWD/bin/cli.js"
TOOLKIT_PROJECT="/absolute/path/to/your-project"
node "$TOOLKIT_CLI" setup-preview
node "$TOOLKIT_CLI" init --target all --project "$TOOLKIT_PROJECT"
node "$TOOLKIT_CLI" doctor --target all --project "$TOOLKIT_PROJECT"Set TOOLKIT_PROJECT to the project containing your diagram. Use --target claude
or --target codex for one client. Keep this checkout available: the installed
skill records its absolute CLI path. Installation guide
covers the packed archive, updates, runtime requirements, and uninstalling.
Start a new Claude Code session in the project. Its installed scoped-edit skill
uses the native CLI for saved-file edits. Try:
Use scoped-edit on
architecture.excalidraw. Read the relevant source and add the missing agent entry point and its connections in the available space. Preserve my notes and existing layout. Show before/after previews and return the editable copy.
Connect the toolkit through standard MCP, rooted at your project:
First inspect any existing registration:
codex mcp get excalidraw_toolkitIf the name is unused, add the connection:
codex mcp add excalidraw_toolkit -- \
node "$TOOLKIT_CLI" mcp --project "$TOOLKIT_PROJECT"This is a persistent Codex user registration; choose an unused name for another
installation. Start a new session in the project and verify inspect_scene,
edit_scene, and read_preview are available, then try the same request above.
The trusted MCP process runs the renderer while Codex's default macOS shell
sandbox stays unchanged. Tool paths are project-relative; edited copies live
under .excalidraw-toolkit/edits/ in that project. Changing projects requires a
connection rooted there. Connection and removal details.
Open an edit receipt or native file with the installed CLI:
node "$TOOLKIT_CLI" preview "/absolute/path/to/receipt.json"
node "$TOOLKIT_CLI" preview "/absolute/path/to/diagram.excalidraw"Draw directly in Working with Excalidraw’s native tools, text, images, and undo/redo.
Inspect a preserved Before, then review an Agent proposal and accept or discard it.
Independent manual edits survive acceptance; conflicts leave your work unchanged.
Save the live diagram as .excalidraw, export PNG, and reopen it here. A local browser
draft recovers changes after reload. Workspace guide.
Run editing requests in your existing coding agent, then open its receipt here for review. An in-page agent conversation is not shipped. Matching CLI retries reuse a verified result, and the original input is never overwritten. Snapshot transitions respect reduced motion.
Recorded from the working review UI using the Codex-produced file above. The agent edit finished before this clip; the recording shows the subsequent browser workflow. Download the WebM · View the reopened result
Native files preserve IDs, ordering, embedded assets, deleted-element history, document settings, and fields outside the permitted change. Unsupported geometry, text that cannot fit, and ambiguous removal policies fail explicitly. See supported operations and examples.
The host agent reads source at exact revisions and supplies focused diagrams,
references, and explicit unknowns. explain-change exports editable before/after
files, a source-linked report, and PNGs at the intended size. Unchanged context
keeps its position; unreadable labels fail the target-size gate.
refresh-diagram compares the accepted generated baseline, your current drawing,
and a new source proposal. Manual positions, labels, styles, and unrelated content
survive. Competing changes appear as conflicts. Review the candidate, then call
adopt-refresh explicitly to accept the new baseline.
These commands take request files prepared by the agent. Read the request guide, evidence contract, comparison targets, and refresh rules.
Run the same workflow from an explicit Git/CI event. Jobs retain their baseline, native result, preview, and report. Duplicate events reuse verified output; superseded jobs cannot replace newer artifacts. Investigation needs your configured agent and model access, or an already prepared proposal.
Publication is off by default. A trusted publisher can reconcile one managed PR comment after its destination, credentials, uploaded artifacts, and visibility are configured. Fork publication is unsupported. See CI setup, examples, and publication.
Saved-file edits and refreshes create copies; they do not merge atomically with an external editor or edit an unsaved live canvas. Source citations identify inspected locations, not proof of runtime behavior or complete coverage. The workspace-scoped MCP tools cover saved-file edits; source comparison and CI run through the CLI on a host that can launch the renderer.
Installed Claude Code and Codex cases were checked separately against native files, actual previews, and final responses. The matched stock-equipped Claude case also succeeded; no speed or quality superiority is claimed. CI used a prepared source proposal, and publisher tests used local HTTP fixtures. Production model access, uploaded links, and repository policy remain deployment setup.
For new diagrams, a separate Claude Code live-canvas integration remains available; see live-canvas workflows.
Future directions, not included: revision-checked edits to an unsaved live canvas, Obsidian round trips, additional backends, and additional diagram views. These are conditional follow-ups, not promised release dates.
For development and Linux browser dependencies, see installation. The installed package supports Node 20+; the source-build requirements above are higher.
MIT. Created by @edwingao28.