Drawgent：把 Claude Code 接到 Excalidraw 画布上

drawgent: your coding agent on a live Excalidraw canvas#

drawgent connectsyour ownClaude Code, Codex or opencode (your install, login, config and repo) to an Excalidraw whiteboard. Ask for a diagram in the chat panel, or writeAGENT: …next to the part of a drawing you want changed. The agent looks at the canvas (screenshot + scene), edits it live, checks the result, and marks the noteDONE.

Quick start#

Prerequisite: one ofclaude,codexoropencodeinstalled and logged in. The Claude and Codex bridges also need Node.js ≥ 18 (npm).

drawgent setup claude# once per agent: claude | codex | opencode
cd~/my-repodrawgent up# new agent session in this repo + canvas in your browser
drawgent up --attach# or: pick one of your running sessions and connect the canvas to it

drawgent setup <agent>#

Checks everything once, fails with the exact fix when something is missing, and writes~/.config/drawgent/config.toml:

1. The agent CLI.Yourclaude/codex/opencodeon PATH.

2. Login. claude auth status,codex login statusoropencode auth list.

3. ACP bridge.

   • opencode speaks ACP itself (opencode acp).
   • Claude Code and Codex use the official ACP adapters. They are installed once into~/.cache/drawgent/adapters(~60 MB),withouttheir bundled agent binaries, and pointed atyourCLI (CLAUDE_CODE_EXECUTABLE,CODEX_PATH).
   • Setup then verifies the ACP handshake.

4. Canvas tools for attached sessions.Only Codex needs a change:codex mcp add drawgent -- drawgent mcp. Claude and opencode get the tools at attach time.

5. Headless Chrome for the renderer.Setup uses your Chrome/Chromium if you have one. Otherwise it proposes:

   • downloadingChrome Headless Shell(Chrome for Testing, ~120 MB, no sudo) into~/.cache/drawgent/chrome, and telling you exactly which system libraries are missing, if any;
   • installing Chromium with your package manager (apt,snap,dnf,pacman,zypper,apk,brew, ornixwithout sudo).

   Non-interactive:--chrome download | system | /path/to/chrome.

drawgent uprefuses to start until setup succeeded for that agent, or if something setup recorded disappeared.

drawgent up#

Runs in the current directory (the workspace):

• starts the editor + API on127.0.0.1:7300(next free port if taken);
• 通过 ACP 启动你的智能体的一个新会话，在工作区中工作；
• 打开你的浏览器。在无头机器上它会打印ssh -L命令。

场景保存在.drawgent/scene.json中，该目录会被自动 git 忽略。

drawgent up --attach [id]#

将画布连接到你已经在运行的会话。不带 id 时，它会列出找到的会话（当前目录优先）并让你选择一个：

使用画布#

• 聊天面板（右侧）：发送请求，观看回复和工具调用流式传入，批准权限提示，按Stop取消一轮。
• 在画布上：在形状旁边或内部写下以AGENT:开头的文本，或从笔记画一个箭头指向形状。它会在你停止输入约 2.5 秒后触发，携带其位置、指向的对象以及附近的内容。智能体将其解析为一个绿色DONE: …笔记。将其编辑回AGENT:以再次发送。
• 提示会排队并一次运行一个。已处理过的排队笔记会被跳过。

drawgent up --room'https://excalidraw.com/#room=<id>,<key>'

• drawgent 作为协作者加入房间（🤖 Agent，带有一个跟随其编辑的光标）。AGENT:人类可以留在 excalidraw.com：他们的
• 笔记会到达你的智能体，其编辑会实时出现在那里。
• 流量使用房间密钥进行端到端加密。空房间从 excalidraw 的 Firestore 存储加载并保存到其中。

本地编辑器镜像该房间，并且仍然有聊天面板。其他命令

• drawgent mcp#drawgent up：带有画布工具的 stdio MCP 服务器。智能体启动它；它会自行找到正在运行的
• drawgent serve：带有显式智能体的低级服务器（--agent claude,codex,opencode按设置，或name=command用于任何 ACP 智能体）；用于脚本和容器。
• 选项用于up/serve：--port，--room，--token（API bearer +?token=在 URL 中），--permissions canvas|ask|all（默认canvas: 绘图工具自动批准，其他任何内容在聊天面板中询问），--data，--settle-ms。

可选：Docker#

docker compose up --build运行一个 canvas 服务器（drawgent + Chromium，无智能体），例如用于在服务器上托管共享画布或房间桥接。智能体从不捆绑：它们始终在你自己的环境中运行。

从源码构建#

npm ci&&npm run build# 编辑器 + 渲染器页面 -> dist/（嵌入到二进制文件中）
cargo install --path .# 或：cargo build --release

智能体工具（MCP）#

get_scene，get_screenshot（视觉；使用element_ids缩放），add_elements（Excalidraw 骨架；箭头按 id 绑定并逐边路由），add_mermaid（自动布局），update_elements（标签跟随形状，绑定的箭头重新路由），delete_elements，clear_canvas，list_instructions，resolve_instruction，set_status。

API#

GET /api/health·GET /api/scene·GET /api/screenshot?ids=&padding=&max=·POST|PATCH|DELETE /api/elements·POST /api/mermaid·POST /api/clear·GET /api/instructions·POST /api/instructions/{id}/resolve·POST /api/status·POST /api/chat {agent?, text}·WS /ws（浏览器同步 + 聊天事件）

测试#

cargotest                          # 分数索引、房间加密/分帧
node scripts/smoke.mjs[url]        # 聊天轮次 + 针对运行中的 drawgent 的 AGENT: 注释
node scripts/e2e-browser.mjs[url]  # 真实浏览器：聊天面板 + 在画布上输入的注释
node scripts/room-e2e.mjs# 全新的 excalidraw.com 房间 ↔ drawgent，双向

布局#

src/（Rust）：

• main.rs: CLI。
• setup.rs，config.rs，chrome.rs: 设置、配置、渲染器安装。
• attach.rs: 会话发现与选择器。
• agents.rs+acp.rs: ACP 驱动（新建 / 分叉会话）。
• live.rs: 实时 opencode / Codex 驱动。
• hub.rs: 路由、注释、聊天日志。
• scene.rs: 存储与编辑操作。
• renderer.rs: 通过 CDP 控制 Chrome。
• mcp.rs: MCP 服务器。
• room.rs: excalidraw.com 客户端。
• fractional.rs，geometry.rs，el.rs: 辅助工具。

web/: 编辑器（main.jsx，chat.jsx）和渲染器页面（render.jsx）。

限制#

• 渲染器需要 Chrome（原生渲染器已在计划中）。
• Claude 的“attach”是一种分叉，因为 Claude Code 没有公开的方式注入到正在运行的终端会话中。
• Codex 实时 attach 已实现，但尚未针对已登录的 Codex 进行测试。
• 每个工作区一个场景。图像/文件不会同步。