drawgent: Visuele AI-integratie
drawgent is een in Rust geschreven applicatie die een brug slaat tussen diverse coding agents (zoals Claude Code, Codex en opencode) en een Excalidraw-canvas. Hiermee kunnen ontwikkelaars visueel communiceren en samenwerken met hun AI-agent.
De belangrijkste functionaliteiten zijn:
- Agent-integratie: Via een setup-proces worden agents gekoppeld aan de tool via ACP-bridges of HTTP API's, waarbij de agent direct in de huidige workspace kan opereren.
- Interactieve Canvas-besturing: Gebruikers kunnen instructies geven via een chatpanel of direct op het canvas door teksten te starten met
AGENT:. De agent verwerkt deze verzoeken en kan elementen op het canvas aanpassen.
- MCP & Vision: Dankzij het Model Context Protocol (MCP) en een headless Chrome renderer kan de agent de scène analyseren (vision), screenshots maken en complexe visuele elementen zoals Mermaid-diagrammen toevoegen.
- Collaboratieve Kamers:
drawgent kan zich voegen bij excalidraw.com kamers als collaborator, waardoor mensen en AI in real-time op hetzelfde canvas kunnen werken via end-to-end versleutelde verbindingen.
- Technische Basis: De tool biedt een uitgebreide API, ondersteunt Docker voor server-hosting en is gebouwd met een focus op modulariteit en snelheid via Rust.
drawgent: Verbind je coding agent met een live Excalidraw-canvas
Functionaliteiten
setup <agent>: Controleert de geïnstalleerde CLI en login, bereidt de ACP-bridge voor (adapters die de binary van de gebruiker aansturen), zoekt of installeert een headless Chrome, en schrijft de configuratie naar ~/.config/drawgent/config.toml.up: Start een nieuwe agent-sessie in de huidige workspace. Met up --attach [id] kunnen draaiende sessies worden weergegeven (Claude fork via ACP, live opencode via HTTP API, live Codex via codex queue).- Interface: Bevat een chatpanel en een
AGENT:-functie voor canvas-notities, inclusief MCP canvas-tools met vision (via een headless Chrome renderer) en een excalidraw.com-room client (AES-GCM, socket.io, Firestore).
- Ontwikkeling: Voorzien van een Makefile met statische musl-builds, een Nix dev shell (fish) en een optioneel server-only Docker-image.
Snelstart
Voorwaarde: Eén van de volgende tools moet zijn geïnstalleerd en ingelogd: claude, codex of opencode. Voor de Claude- en Codex-bridges is daarnaast Node.js $\ge$ 18 (npm) vereist.
drawgent setup claude # Eenmalig per agent: claude | codex | opencode
cd ~/my-repo
drawgent up # Nieuwe agent-sessie in deze repo + canvas in de browser
drawgent up --attach # Kies een van de draaiende sessies en verbind het canvas ermee
Gedetailleerde commando's
drawgent setup <agent>
Dit commando voert een eenmalige controle uit, geeft exacte oplossingen bij ontbrekende componenten en schrijft de configuratie naar ~/.config/drawgent/config.toml. De volgende zaken worden gecontroleerd:
- Agent CLI: Controleert of
claude, codex of opencode op de PATH staat.
- Login: Controleert de status via
claude auth status, codex login status of opencode auth list.
- ACP-bridge:
opencode spreekt van zichzelf ACP (opencode acp).- Claude Code en Codex maken gebruik van de officiële ACP-adapters. Deze worden eenmalig geïnstalleerd in
~/.cache/drawgent/adapters (~60 MB), zonder de gebundelde agent-binaries, en worden gekoppeld aan de CLI van de gebruiker (CLAUDECODEEXECUTABLE, CODEX_PATH).
- De setup verifieert vervolgens de ACP-handshake.
- Canvas-tools: Alleen voor Codex is een aanpassing nodig:
codex mcp add drawgent -- drawgent mcp. Claude en opencode ontvangen de tools tijdens het koppelen (attach).
- Headless Chrome: De renderer maakt gebruik van de bestaande Chrome/Chromium installatie. Indien niet aanwezig, stelt de setup het volgende voor:
- Het downloaden van de Chrome Headless Shell (Chrome for Testing, ~120 MB, geen sudo nodig) naar
~/.cache/drawgent/chrome, inclusief melding van ontbrekende systeembibliotheken.
- Het installeren van Chromium via een package manager (apt, snap, dnf, pacman, zypper, apk, brew, of nix zonder sudo).
- Niet-interactief: Gebruik
--chrome download | system | /path/to/chrome.
drawgent up weigert te starten totdat de setup voor die agent is geslaagd of als een geconfigureerd onderdeel is verdwenen.
drawgent up
Dit commando wordt uitgevoerd in de huidige directory (de workspace):
- Start de editor en API op
127.0.0.1:7300 (of de volgende vrije poort).
- Start een nieuwe sessie van de agent via ACP, werkend in de workspace.
- Opent de browser. Op een headless machine wordt in plaats daarvan het
ssh -L commando geprint.
- De scène wordt bewaard in
.drawgent/scene.json, wat automatisch wordt genegeerd door git.
drawgent up --attach [id]
Verbindt het canvas met een reeds draaiende sessie. Zonder ID wordt een lijst met gevonden sessies getoond (met de huidige directory eerst), waarna een keuze kan worden gemaakt:
| Agent | Discovery-methode | Verbindingstype |
|---|
| Claude Code | claude agents --json | fork: een nieuwe sessie met het volledige gesprek, aangestuurd door drawgent via ACP. De terminal-sessie blijft ongewijzigd. |
| opencode | Lokale servers: opencode --port 4096 (of opencode serve) | live: berichten gaan naar de actieve sessie (zichtbaar in de TUI); drawgent voegt MCP-tools toe aan de server; interacties in de TUI worden gespiegeld in het chatpanel. |
| Codex | Sessies in ~/.codex/sessions | live: codex queue --thread <id>; antwoorden worden gespiegeld vanuit het rollout-bestand. De sessie vereist de drawgent MCP (geregistreerd via setup). |
Gebruik van het canvas
- Chatpanel (rechterzijde): Verstuur verzoeken, volg antwoorden en tool-calls in real-time, keur machtigingsverzoeken goed of druk op 'Stop' om een beurt te annuleren.
- Op het canvas: Schrijf een tekst die begint met
AGENT: naast of in een vorm, of trek een pijl van de notitie naar een vorm. Na ongeveer 2,5 seconde stopten met typen wordt het verzoek verzonden, inclusief positie, het doel van de pijl en de nabijgelegen elementen. De agent verwerkt dit en verandert de notitie in een groene DONE: … notitie. Verander dit terug naar AGENT: om het opnieuw te verzenden.
Prompts worden in een wachtrij geplaatst en één voor één uitgevoerd. Een notitie in de wachtrij die al is behandeld, wordt overgeslagen.
excalidraw.com kamers
Gebruik het commando: drawgent up --room 'https://excalidraw.com/#room=<id>,<key>'
drawgent voegt zich bij de kamer als collaborator (🤖 Agent, met een cursor die de bewerkingen volgt). Mensen kunnen op excalidraw.com blijven: hun AGENT:-notities bereiken de agent, en de bewerkingen van de agent verschijnen direct in de kamer.
Het verkeer is end-to-end versleuteld met de kamer-sleutel. Lege kamers worden geladen vanuit en opgeslagen in de Firestore-opslag van Excalidraw. De lokale editor spiegelt de kamer en behoudt het chatpanel.
Overige commando's
drawgent mcp: Een stdio MCP-server met de canvas-tools. Agents starten deze server; de server vindt zelf de draaiende drawgent up instantie.drawgent serve: Een low-level server met expliciete agents (--agent claude,codex,opencode zoals geconfigureerd, of name=command voor elke ACP-agent). Geschikt voor scripts en containers.- Opties voor
up / serve: --port, --room, --token (API bearer + ?token= in de URL), --permissions canvas|ask|all (standaard is canvas: tekentools worden automatisch goedgekeurd, andere zaken via het chatpanel), --data, --settle-ms.
Optioneel: Docker
docker compose up --build start een canvas-server (drawgent + Chromium, zonder agents). Dit kan worden gebruikt om een gedeeld canvas of een room-bridge op een server te hosten. Agents zijn nooit gebundeld; deze draaien altijd via de eigen setup van de gebruiker.
Bouwen vanuit broncode
npm ci && npm run build # Editor + renderer pagina's -> dist/ (ingebed in de binary)
cargo install --path . # Of: cargo build --release
Agent tools (MCP)
De volgende tools zijn beschikbaar: getscene, getscreenshot (vision; zoom met elementids), addelements (Excalidraw skeletons; pijlen binden via id en worden edge-to-edge gerouteerd), addmermaid (auto-layout), updateelements (labels volgen vormen, gebonden pijlen worden opnieuw gerouteerd), deleteelements, clearcanvas, listinstructions, resolveinstruction, set_status.
API
GET /api/healthGET /api/sceneGET /api/screenshot?ids=&padding=&max=POST|PATCH|DELETE /api/elementsPOST /api/mermaidPOST /api/clearGET /api/instructionsPOST /api/instructions/{id}/resolvePOST /api/statusPOST /api/chat {agent?, text}WS /ws (browser synchronisatie + chat events)
Testen
cargo test: Test fractionele indexen, room crypto/framing.node scripts/smoke.mjs [url]: Test chat-beurten en AGENT:-notities tegen een draaiende drawgent.node scripts/e2e-browser.mjs [url]: Test via een echte browser: chatpanel + notities getypt op het canvas.node scripts/room-e2e.mjs: Test interactie tussen een verse excalidraw.com kamer en drawgent in beide richtingen.
Projectstructuur
src/ (Rust)
main.rs: CLI.setup.rs, config.rs, chrome.rs: Setup, configuratie en installatie van de renderer.attach.rs: Sessie-detectie en selectie.agents.rs + acp.rs: ACP-driver (nieuwe / fork sessies).live.rs: Live opencode / Codex drivers.hub.rs: Routing, notities, chat-log.scene.rs: Opslag en bewerkingsoperaties.renderer.rs: Chrome via CDP.mcp.rs: MCP-server.room.rs: excalidraw.com client.fractional.rs, geometry.rs, el.rs: Helpers.
web/
- Editor (
main.jsx, chat.jsx) en renderer-pagina (render.jsx).
Beperkingen
- De renderer vereist Chrome (een native renderer is in planning).
- De Claude "attach" functie is een fork, omdat Claude Code geen publieke manier biedt om in een draaiende terminal-sessie te injecteren.
- De Codex live-attach is geïmplementeerd, maar nog niet getest tegen een ingelogde Codex-gebruiker.
- Er is één scène per workspace. Afbeeldingen en bestanden worden niet gesynchroniseerd.
drawgent: Verbind je coding agent met een live Excalidraw-canvas
Functionaliteiten
setup <agent>: Controleert de geïnstalleerde CLI en login, bereidt de ACP-bridge voor (adapters die de binary van de gebruiker aansturen), zoekt of installeert een headless Chrome, en schrijft de configuratie naar ~/.config/drawgent/config.toml.up: Start een nieuwe agent-sessie in de huidige workspace. Met up --attach [id] kunnen draaiende sessies worden weergegeven (Claude fork via ACP, live opencode via HTTP API, live Codex via codex queue).- Interface: Bevat een chatpanel en een
AGENT:-functie voor canvas-notities, inclusief MCP canvas-tools met vision (via een headless Chrome renderer) en een excalidraw.com-room client (AES-GCM, socket.io, Firestore).
- Ontwikkeling: Voorzien van een Makefile met statische musl-builds, een Nix dev shell (fish) en een optioneel server-only Docker-image.
Snelstart
Voorwaarde: Eén van de volgende tools moet zijn geïnstalleerd en ingelogd: claude, codex of opencode. Voor de Claude- en Codex-bridges is daarnaast Node.js $\ge$ 18 (npm) vereist.
drawgent setup claude # Eenmalig per agent: claude | codex | opencode
cd ~/my-repo
drawgent up # Nieuwe agent-sessie in deze repo + canvas in de browser
drawgent up --attach # Kies een van de draaiende sessies en verbind het canvas ermee
Gedetailleerde commando's
drawgent setup <agent>
Dit commando voert een eenmalige controle uit, geeft exacte oplossingen bij ontbrekende componenten en schrijft de configuratie naar ~/.config/drawgent/config.toml. De volgende zaken worden gecontroleerd:
- Agent CLI: Controleert of
claude, codex of opencode op de PATH staat.
- Login: Controleert de status via
claude auth status, codex login status of opencode auth list.
- ACP-bridge:
opencode spreekt van zichzelf ACP (opencode acp).- Claude Code en Codex maken gebruik van de officiële ACP-adapters. Deze worden eenmalig geïnstalleerd in
~/.cache/drawgent/adapters (~60 MB), zonder de gebundelde agent-binaries, en worden gekoppeld aan de CLI van de gebruiker (CLAUDECODEEXECUTABLE, CODEX_PATH).
- De setup verifieert vervolgens de ACP-handshake.
- Canvas-tools: Alleen voor Codex is een aanpassing nodig:
codex mcp add drawgent -- drawgent mcp. Claude en opencode ontvangen de tools tijdens het koppelen (attach).
- Headless Chrome: De renderer maakt gebruik van de bestaande Chrome/Chromium installatie. Indien niet aanwezig, stelt de setup het volgende voor:
- Het downloaden van de Chrome Headless Shell (Chrome for Testing, ~120 MB, geen sudo nodig) naar
~/.cache/drawgent/chrome, inclusief melding van ontbrekende systeembibliotheken.
- Het installeren van Chromium via een package manager (apt, snap, dnf, pacman, zypper, apk, brew, of nix zonder sudo).
- Niet-interactief: Gebruik
--chrome download | system | /path/to/chrome.
drawgent up weigert te starten totdat de setup voor die agent is geslaagd of als een geconfigureerd onderdeel is verdwenen.
drawgent up
Dit commando wordt uitgevoerd in de huidige directory (de workspace):
- Start de editor en API op
127.0.0.1:7300 (of de volgende vrije poort).
- Start een nieuwe sessie van de agent via ACP, werkend in de workspace.
- Opent de browser. Op een headless machine wordt in plaats daarvan het
ssh -L commando geprint.
- De scène wordt bewaard in
.drawgent/scene.json, wat automatisch wordt genegeerd door git.
drawgent up --attach [id]
Verbindt het canvas met een reeds draaiende sessie. Zonder ID wordt een lijst met gevonden sessies getoond (met de huidige directory eerst), waarna een keuze kan worden gemaakt:
| Agent | Discovery-methode | Verbindingstype |
|---|
| Claude Code | claude agents --json | fork: een nieuwe sessie met het volledige gesprek, aangestuurd door drawgent via ACP. De terminal-sessie blijft ongewijzigd. |
| opencode | Lokale servers: opencode --port 4096 (of opencode serve) | live: berichten gaan naar de actieve sessie (zichtbaar in de TUI); drawgent voegt MCP-tools toe aan de server; interacties in de TUI worden gespiegeld in het chatpanel. |
| Codex | Sessies in ~/.codex/sessions | live: codex queue --thread <id>; antwoorden worden gespiegeld vanuit het rollout-bestand. De sessie vereist de drawgent MCP (geregistreerd via setup). |
Gebruik van het canvas
- Chatpanel (rechterzijde): Verstuur verzoeken, volg antwoorden en tool-calls in real-time, keur machtigingsverzoeken goed of druk op 'Stop' om een beurt te annuleren.
- Op het canvas: Schrijf een tekst die begint met
AGENT: naast of in een vorm, of trek een pijl van de notitie naar een vorm. Na ongeveer 2,5 seconde stopten met typen wordt het verzoek verzonden, inclusief positie, het doel van de pijl en de nabijgelegen elementen. De agent verwerkt dit en verandert de notitie in een groene DONE: … notitie. Verander dit terug naar AGENT: om het opnieuw te verzenden.
Prompts worden in een wachtrij geplaatst en één voor één uitgevoerd. Een notitie in de wachtrij die al is behandeld, wordt overgeslagen.
excalidraw.com kamers
Gebruik het commando: drawgent up --room 'https://excalidraw.com/#room=<id>,<key>'
drawgent voegt zich bij de kamer als collaborator (🤖 Agent, met een cursor die de bewerkingen volgt). Mensen kunnen op excalidraw.com blijven: hun AGENT:-notities bereiken de agent, en de bewerkingen van de agent verschijnen direct in de kamer.
Het verkeer is end-to-end versleuteld met de kamer-sleutel. Lege kamers worden geladen vanuit en opgeslagen in de Firestore-opslag van Excalidraw. De lokale editor spiegelt de kamer en behoudt het chatpanel.
Overige commando's
drawgent mcp: Een stdio MCP-server met de canvas-tools. Agents starten deze server; de server vindt zelf de draaiende drawgent up instantie.drawgent serve: Een low-level server met expliciete agents (--agent claude,codex,opencode zoals geconfigureerd, of name=command voor elke ACP-agent). Geschikt voor scripts en containers.- Opties voor
up / serve: --port, --room, --token (API bearer + ?token= in de URL), --permissions canvas|ask|all (standaard is canvas: tekentools worden automatisch goedgekeurd, andere zaken via het chatpanel), --data, --settle-ms.
Optioneel: Docker
docker compose up --build start een canvas-server (drawgent + Chromium, zonder agents). Dit kan worden gebruikt om een gedeeld canvas of een room-bridge op een server te hosten. Agents zijn nooit gebundeld; deze draaien altijd via de eigen setup van de gebruiker.
Bouwen vanuit broncode
npm ci && npm run build # Editor + renderer pagina's -> dist/ (ingebed in de binary)
cargo install --path . # Of: cargo build --release
Agent tools (MCP)
De volgende tools zijn beschikbaar: getscene, getscreenshot (vision; zoom met elementids), addelements (Excalidraw skeletons; pijlen binden via id en worden edge-to-edge gerouteerd), addmermaid (auto-layout), updateelements (labels volgen vormen, gebonden pijlen worden opnieuw gerouteerd), deleteelements, clearcanvas, listinstructions, resolveinstruction, set_status.
API
GET /api/healthGET /api/sceneGET /api/screenshot?ids=&padding=&max=POST|PATCH|DELETE /api/elementsPOST /api/mermaidPOST /api/clearGET /api/instructionsPOST /api/instructions/{id}/resolvePOST /api/statusPOST /api/chat {agent?, text}WS /ws (browser synchronisatie + chat events)
Testen
cargo test: Test fractionele indexen, room crypto/framing.node scripts/smoke.mjs [url]: Test chat-beurten en AGENT:-notities tegen een draaiende drawgent.node scripts/e2e-browser.mjs [url]: Test via een echte browser: chatpanel + notities getypt op het canvas.node scripts/room-e2e.mjs: Test interactie tussen een verse excalidraw.com kamer en drawgent in beide richtingen.
Projectstructuur
src/ (Rust)
main.rs: CLI.setup.rs, config.rs, chrome.rs: Setup, configuratie en installatie van de renderer.attach.rs: Sessie-detectie en selectie.agents.rs + acp.rs: ACP-driver (nieuwe / fork sessies).live.rs: Live opencode / Codex drivers.hub.rs: Routing, notities, chat-log.scene.rs: Opslag en bewerkingsoperaties.renderer.rs: Chrome via CDP.mcp.rs: MCP-server.room.rs: excalidraw.com client.fractional.rs, geometry.rs, el.rs: Helpers.
web/
- Editor (
main.jsx, chat.jsx) en renderer-pagina (render.jsx).
Beperkingen
- De renderer vereist Chrome (een native renderer is in planning).
- De Claude "attach" functie is een fork, omdat Claude Code geen publieke manier biedt om in een draaiende terminal-sessie te injecteren.
- De Codex live-attach is geïmplementeerd, maar nog niet getest tegen een ingelogde Codex-gebruiker.
- Er is één scène per workspace. Afbeeldingen en bestanden worden niet gesynchroniseerd.
Groetjes,