Drawgent: Coding agent on a live Excalidraw canvas

drawgent: your coding agent on a live Excalidraw canvas#

drawgent connects your own Claude Code, Codex or opencode (your install, login, config and repository) to an Excalidraw whiteboard. Ask for a diagram in the chat panel, write AGENT: … next to the part of a drawing you want changed, or point at it with the laser.

The agent looks at the canvas (scene and screenshot), edits it live and checks its own layout. It keeps every box linked to the code it stands for, and it can change the code to match what you drew.

How it works#

• The server: drawgent is a single binary. It serves the editor, keeps the boards, and runs a headless Chrome to render screenshots.
• The agent: drawgent starts your agent, or connects a session you already run, and gives it canvas tools over MCP.
• Rooms: in a shared excalidraw.com room or a self-hosted Excalidraw document, drawgent is one more collaborator.

Install#

drawgent is a single static binary. Download the latest release, 0.2.1, for your platform:

Or from a terminal (set t to your platform's name from the table):

v=0.2.1 t=x86_64-unknown-linux-musl     # or aarch64-unknown-linux-musl, aarch64-apple-darwin, x86_64-apple-darwin
base=https://tangled.org/yanndegat.tngl.sh/drawgent/tags/v$v/download
curl -fLO $base/drawgent-$v-$t.tar.gz -fLO $base/drawgent-$v-$t.tar.gz.sha256
sha256sum -c drawgent-$v-$t.tar.gz.sha256                  # macOS: shasum -a 256 -c …
tar xzf drawgent-$v-$t.tar.gz && install drawgent-$v-$t/drawgent ~/.local/bin/

• macOS: the binary isn't notarized. Run xattr -d com.apple.quarantine ~/.local/bin/drawgent once.
• Other versions: every release is on the tags page.
• From source: see Development.

Quick start#

You need one agent installed and logged in (claude, codex or opencode). Nothing else: no Node.js, no Docker.

drawgent setup claude        # once per agent: checks the CLI, the login, the bridge, a renderer
cd ~/my-repo
drawgent up                  # new agent session in this repo + the canvas in your browser
drawgent up --attach         # or: connect the canvas to a session you already run

Then ask: "Draw the architecture of this repository, grouped by role, each box linked to its code." The full walkthrough, with install and troubleshooting, is in Getting started.

Features#

Talk to the agent where the drawing is#

• Chat panel: replies and tool calls stream in, permission prompts show as buttons, and Stop cancels a turn. Under each turn: the tokens it used, context use and cost.
• AGENT: notes: a note written on the canvas fires once you stop typing, with what it points at. The agent answers with a green DONE: note.
• Undo: agent edits go on the undo stack. Ctrl+Z reverts them, and ↶ Undo reverts a whole turn.

→ The canvas

Point with the laser, pick a task#

Circle, cross out, connect or push apart parts of a diagram with Excalidraw's laser (K). drawgent recognises the gesture and what it's on. Two seconds later, a poll offers 2 or 3 tasks that would be tedious by hand, plus Other…:

• Drill down into a component, from its code;
• Trace A → B in the code;
• Remove from the architecture, with its impact on the code;
• Make room and re-balance.

Crossing out a box also tells the agent what the deletion breaks.

→ Laser and gestures

Diagrams linked to code#

• Code links: every box can point at a file, lines and a symbol, and opens it in the Code tab. Links are checked as ✅ ok, ↕ moved, ⚠ stale or ❌ missing, and drawgent check fails CI when they break.
• Repo map: 🗺 Map repo draws the workspace as a treemap, with every file linked.
• Pointing at code: point at folders, files and lines instead of typing paths.
• 🔨 Build what I drew: change the diagram and the agent implements the change, marking progress on the canvas.

→ Code and diagrams

Boards, and diagrams in the repository#

• Boards: as many boards per workspace as you like. Move or copy diagrams between them, or split one by its frames.
• In the repository: --diagram docs/architecture.excalidraw keeps a board in a clean, diffable .excalidraw file that follows git pull.

→ The canvas

Your agent, your way#

• Agents: Claude Code and Codex through bridges built into drawgent, opencode natively.
• Sessions: a new one, or --attach to one you're running; Claude sessions are forked, opencode and Codex sessions joined live.
• Permissions: --permissions canvas|ask|all.

→ Agents

Shared documents and the browser extension#

• Rooms: join an excalidraw.com room, or any document on a self-hosted Excalidraw (drawgent remote add, behind SSO or not), as a collaborator.
• Firefox extension: a drawgent sidebar next to the document you have open. One click joins it, and your laser strokes there become gestures.

→ Shared rooms · Browser extension

Runs where you work#

• Background: drawgent up -d, then status and down.
• Canvas only: --no-workspace, for diagrams with no codebase behind them.
• Remote machines: the ssh -L hint on headless machines, --token for anything exposed.

→ Running drawgent

Documentation#

Commands#

Every option is in the reference.

Limits#

• Chrome: the renderer needs Chrome or Chromium. setup finds or installs one.
• Claude --attach: it's a fork, because Claude Code has no public way to inject messages into a running terminal session.
• Codex --attach: live attach hasn't been tested against a logged-in Codex yet.
• Rooms: a room mirrors one board, and images aren't synced. On self-hosted servers, a browser must have the document open (it saves it). See Shared rooms › Limits.
• macOS: builds are cross-compiled and not notarized, and they haven't been tested on a real Mac yet.

License#

drawgent is free software: GPL-3.0-or-later, with no warranty. drawgent licenses prints the notice.

The binary bundles third-party work under GPL-compatible licenses (MIT, Apache-2.0, BSD, ISC, OFL for the fonts and more). The full texts are in THIRD_PARTY_LICENSES.md.

The coding agents and Chrome aren't part of drawgent: they run from your own install, under their own terms.