yanndegat.tngl.sh/drawgent at principal · Tangled

drawgent connects your personal Claude Code, Codex or opencode (your set up, login, config and
repo) to an Excalidraw whiteboard. Ask for a diagram within the chat panel, or write AGENT: …
subsequent to the a part of a drawing you need modified. The agent appears on the canvas (screenshot +
scene), edits it reside, checks the outcome, and marks the be aware DONE.

Quick begin#

Prerequisite: one in all claude, codex or opencode put in and logged in. The Claude and
Codex bridges additionally want Node.js ≥ 18 (npm).

drawgent setup claude        # as soon as per agent: claude | codex | opencode
cd ~/my-repo
drawgent up                  # new agent session on this repo + canvas in your browser
drawgent up --attach         # or: choose one in all your working classes and join the canvas to it

drawgent setup #

Checks every thing as soon as, fails with the precise repair when one thing is lacking, and writes
~/.config/drawgent/config.toml:

1. The agent CLI. Your claude / codex / opencode on PATH.

2. Login. claude auth standing, codex login standing or opencode auth record.

3. ACP bridge.

   • opencode speaks ACP itself (opencode acp).
   • Claude Code and Codex use the official ACP adapters. They are put in as soon as into
     ~/.cache/drawgent/adapters (~60 MB), with out their bundled agent binaries, and pointed
     at your CLI (CLAUDE_CODE_EXECUTABLE, CODEX_PATH).
   • Setup then verifies the ACP handshake.

4. Canvas instruments for hooked up classes. Only Codex wants a change:
   codex mcp add drawgent -- drawgent mcp. Claude and opencode get the instruments at connect time.

5. Headless Chrome for the renderer. Setup makes use of your Chrome/Chromium if in case you have one.
   Otherwise it proposes:

   • downloading Chrome Headless Shell (Chrome for Testing, ~120 MB, no sudo) into
     ~/.cache/drawgent/chrome, and telling you precisely which system libraries are lacking, if
     any;
   • putting in Chromium together with your bundle supervisor (apt, snap, dnf, pacman, zypper,
     apk, brew, or nix with out sudo).

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

drawgent up refuses to begin till setup succeeded for that agent, or if one thing setup
recorded disappeared.

drawgent up#

Runs within the present listing (the workspace):

• begins the editor + API on 127.0.0.1:7300 (subsequent free port if taken);
• begins a brand new session of your agent over ACP, working within the workspace;
• opens your browser. On a headless field it prints the ssh -L command as an alternative.

The scene is stored in .drawgent/scene.json, which is git-ignored mechanically.

drawgent up --attach [id]#

Connects the canvas to a session you already run. Without an id it lists the classes it
finds (present listing first) and allows you to choose one:

agent	discovery	how the canvas reaches it
Claude Code	claude brokers --json (interactive and background classes)	fork: a brand new session carrying the total dialog, pushed by drawgent over ACP. Your terminal session is left untouched
opencode	opencode servers listening domestically: begin the TUI with opencode --port 4096 (or opencode serve)	reside: messages go into your working session (you see them in your TUI); drawgent provides its MCP instruments to that server at runtime; replies, instrument calls and prompts you kind within the TUI are mirrored into the chat panel
Codex	classes in ~/.codex/classes	reside: codex queue --thread ; replies are mirrored from the session’s rollout file. The session wants the drawgent MCP (registered by setup, loaded when Codex begins)

Using the canvas#

• Chat panel (proper facet): ship a request, watch replies and power calls stream in, approve
  permission prompts, press Stop to cancel a flip.
• On the canvas: write a textual content beginning with AGENT: subsequent to or inside a form, or draw an
  arrow from the be aware to a form. It fires about 2.5 s after you cease typing, with its
  place, what it factors at and what’s close by. The agent resolves it right into a inexperienced
  DONE: … be aware. Edit it again to AGENT: to ship it once more.
• Prompts are queued and run one after the other. A queued be aware that was already dealt with is skipped.

drawgent up --room 'https://excalidraw.com/#room=,'

• drawgent joins the room as a collaborator (🤖 Agent, with a cursor that follows its edits).
  Humans can keep on excalidraw.com: their AGENT: notes attain your agent, and its edits
  seem there reside.
• Traffic is end-to-end encrypted with the room key. Empty rooms are loaded from and saved to
  excalidraw’s Firestore storage.
• The native editor mirrors the room and nonetheless has the chat panel.

Other instructions#

• drawgent mcp: stdio MCP server with the canvas instruments. Agents launch it; it finds the working
  drawgent up by itself.
• drawgent serve: low-level server with specific brokers (--agent claude,codex,opencode as arrange,
  or title=command for any ACP agent); for scripts and containers.
• Options for up / serve: --port, --room, --token (API bearer + ?token= within the URL),
  --permissions canvas|ask|all (default canvas: drawing instruments auto-approved, the rest
  requested within the chat panel), --data, --settle-ms.

Optional: Docker#

docker compose up --build runs a canvas server (drawgent + Chromium, no brokers), e.g. to
host a shared canvas or a room bridge on a server. Agents are by no means bundled: they at all times run
with your personal setup.

Build from supply#

npm ci && npm run construct      # editor + renderer pages -> dist/ (embedded into the binary)
cargo set up --path .       # or: cargo construct --release

get_scene, get_screenshot (imaginative and prescient; zoom with element_ids), add_elements (Excalidraw
skeletons; arrows bind by id and are routed edge-to-edge), add_mermaid (auto-layout),
update_elements (labels observe shapes, certain arrows re-route), delete_elements,
clear_canvas, list_instructions, resolve_instruction, set_status.

API#

GET /api/well being · GET /api/scene · GET /api/screenshot?ids=&padding=&max= ·
POST|PATCH|DELETE /api/parts · POST /api/mermaid · POST /api/clear ·
GET /api/directions · POST /api/directions/{id}/resolve · POST /api/standing ·
POST /api/chat {agent?, textual content} · WS /ws (browser sync + chat occasions)

Tests#

cargo take a look at                          # fractional indices, room crypto/framing
node scripts/smoke.mjs [url]        # chat flip + AGENT: be aware towards a working drawgent
node scripts/e2e-browser.mjs [url]  # actual browser: chat panel + be aware typed on the canvas
node scripts/room-e2e.mjs           # contemporary excalidraw.com room ↔ drawgent, each instructions

Layout#

src/ (Rust):

• principal.rs: CLI.
• setup.rs, config.rs, chrome.rs: setup, config, renderer set up.
• connect.rs: session discovery and picker.
• brokers.rs + acp.rs: ACP driver (new / fork classes).
• reside.rs: reside opencode / Codex drivers.
• hub.rs: routing, notes, chat log.
• scene.rs: retailer and edit operations.
• renderer.rs: Chrome over CDP.
• mcp.rs: MCP server.
• room.rs: excalidraw.com consumer.
• fractional.rs, geometry.rs, el.rs: helpers.

net/: editor (principal.jsx, chat.jsx) and renderer web page (render.jsx).

Limits#

• The renderer wants Chrome (a local renderer is deliberate).
• Claude “connect” is a fork, as a result of Claude Code has no public method to inject right into a working
  terminal session.
• Codex reside connect is carried out, however was not but examined towards a logged-in Codex.
• One scene per workspace. Images/recordsdata aren’t synced.