drawgent – 실시간 Excalidraw 캔버스 기반 AI 코딩 에이전트

TL;DR

drawgent는 사용자의 Claude Code, Codex 또는 opencode 인스턴스를 Excalidraw 화이트보드에 연결하여, 캔버스에 AGENT: 메모를 입력하거나 레이저 영역을 사용하여 LLM이 다이어그램을 실시간으로 편집하도록 합니다. 이를 통해 시각적 브레인스토밍이 코드 인식 다이어그램 업데이트를 직접 구동하는 양방향 워크플로우가 생성됩니다.

drawgent의 기능

실시간 캔버스 편집 – 에이전트가 스크린샷과 장면 스냅샷을 관찰하고, MCP 도구 호출(요소 추가, 업데이트, 삭제)을 실행하며, 완료 시 메모를 DONE:으로 표시합니다.
다중 백엔드 – 각 ACP 어댑터를 통해 Claude Code, Codex 및 opencode를 지원합니다. 에이전트 바이너리는 포함되어 있지 않으며, 사용자가 직접 CLI를 제공해야 합니다.
두 가지 상호작용 모드 –
1. 채팅 패널: 웹 UI 오른쪽에서 텍스트 요청을 입력합니다.
2. 캔버스 내 트리거: AGENT: 텍스트 메모나 레이저 영역을 사용하면 짧은 일시 중지 후 에이전트가 자동으로 호출됩니다.
버전 관리 다이어그램 – --diagram 옵션을 사용하면 캔버스가 깔끔한 .excalidraw 파일로 저장되어 Git에 커밋할 수 있으며, 변경 사항이 생기면 실시간 뷰와 동기화됩니다.

빠른 시작 체크리스트

지원되는 에이전트(claude, codex, opencode) 중 하나를 설치하고 로그인합니다.
drawgent setup <agent>를 실행합니다. 이 명령은 CLI, 로그인 상태, ACP 브리지, 캔버스 도구 및 Chrome 렌더러를 검증하고 ~/.config/drawgent/config.toml을 작성합니다.

저장소 디렉토리에서 세션을 시작합니다:

drawgent up               # 새 에이전트 세션을 시작하고 캔버스를 엽니다
# 또는 기존 세션에 연결
drawgent up --attach

선택적으로 다이어그램을 저장합니다:

drawgent up --diagram docs/architecture.excalidraw

아키텍처 개요

drawgent architecture

브라우저 UI – 채팅 패널과 레이저 영역 처리를 포함하는 React 기반 편집기.
drawgent 서버 (Rust) – ACP 세션, MCP 도구 서버, Chrome 렌더러 및 WebSocket 동기화를 관리합니다.
에이전트 프로세스 – MCP 호출을 수신하는 포크(fork) 또는 실시간 연결된 Claude/Codex/opencode 세션.
Chrome headless – 시각적 정보(get_screenshot)와 요소 기하학적 구조를 위해 캔버스를 렌더링합니다.

핵심 명령어

명령어	목적
`drawgent setup <agent>`	환경 검증, ACP 어댑터 설치, Chrome 구성, `config.toml` 작성.
`drawgent up`	새 에이전트 세션 시작, UI 실행, `127.0.0.1:7300`에서 캔버스 서비스 제공.
`drawgent up --attach [id]`	실행 중인 에이전트 세션(Claude 포크, opencode 실시간 TUI 또는 Codex 큐)에 UI 연결.
`drawgent up --diagram <path>`	실시간 캔버스를 Git으로 추적되는 `.excalidraw` 파일로 저장.
`drawgent up --room <url>`	협업 봇(`🤖 Agent`)으로 기존 Excalidraw.com 방에 참여.
`drawgent mcp`	사용자 지정 스크립트를 위한 캔버스 도구를 노출하는 독립형 MCP 서버.
`drawgent serve`	컨테이너 배포를 위한 저수준 서버; `--agent` 플래그를 통해 에이전트 지정.

캔버스 효과적으로 사용하기

AGENT: 메모 – 도형 옆에 접두사를 배치하거나 화살표를 그립니다. 입력을 멈추면 drawgent가 약 2.5초 대기한 후 대상을 확인하고 녹색 DONE: 메모로 응답합니다.
레이저 영역 – Excalidraw의 레이저(K)를 활성화하고 영역을 원으로 감싸면 빨간색 외곽선이 나타납니다. 채팅 패널이 열리며 포함된 요소 목록(예: 🔴 Laser zone · API, Redis)이 표시됩니다. 다음 메시지는 영역 데이터와 함께 전송되며, 에이전트가 완료되면 외곽선이 사라집니다.
권한 모델 – 기본적으로 그리기 도구는 자동 승인(canvas 권한)됩니다. 다른 작업(예: 파일 쓰기)은 채팅 패널에서 명시적 승인이 필요합니다.

지속성 및 협업

Git 추적 다이어그램 – .excalidraw 파일은 실시간 요소만 포함하며, 예쁘게 출력되고 캔버스가 변경될 때만 업데이트되어 깔끔한 diff를 생성합니다.
방 모드 – Excalidraw.com 방 URL을 제공하면 drawgent가 협업자로 참여합니다. 트래픽은 방 키로 종단간 암호화되며, 로컬 UI는 원격 방을 미러링합니다.
Docker 옵션 – docker compose up --build는 에이전트 없이 캔버스 서버(drawgent + Chromium)를 실행하며, 공유 화이트보드나 방 브리지에 유용합니다.

빌드 및 배포

소스에서 빌드 – npm ci && npm run build로 웹 에셋을 빌드한 후, cargo install --path .로 바이너리를 생성합니다.
정적 Linux – make musl은 완전히 정적인 x86_64 바이너리를 생성합니다. ARM의 경우 MUSL_TARGET을 설정하세요.
macOS universal – make darwin은 Zig를 사용하여 Linux에서 유니버설 바이너리(Intel + Apple Silicon)를 교차 빌드합니다. arm64 슬라이스는 ad-hoc 서명됩니다.
의존성 – 렌더링을 위해 Chrome/Chromium이 필요합니다. 설치 프로그램은 헤드리스 셸을 다운로드하거나 시스템 패키지 관리자를 사용할 수 있습니다.

Hacker News 커뮤니티 인사이트

seemaze는 Excalidraw가 이미 자체 MCP 엔드포인트와 서버(https://mcp.excalidraw.com)를 제공하고 있다고 지적합니다. drawgent의 사용자 지정 MCP 계층은 공식 엔드포인트가 아직 노출하지 않는 Claude 및 Codex용 실시간 연결 기능을 추가합니다.

armanj는 Obsidian 내에서 Mermaid를 사용하는 개인 워크플로우를 공유하며, Mermaid가 "에이전트 친화적"이긴 하지만 drawgent는 캔버스를 직접 편집함으로써 더 풍부한 시각적 피드백 루프를 제공한다고 언급합니다.

4ndrewl은 다이어그램 작성의 진정한 가치는 그것이 유발하는 사고에 있으며, drawgent는 LLM이 스케치를 즉시 반복하도록 함으로써 이 원칙을 지원한다고 강조합니다.

raesene9는 대안으로 Excalidraw Obsidian 플러그인을 언급하지만, drawgent의 다이어그램 저장 기능과 기존 에이전트 세션에 연결하는 능력은 코드베이스와의 더 긴밀한 통합을 제공한다고 말합니다.

bad_haircut72는 아키텍처 다이어그램 생성을 위한 또 다른 옵션으로 whiteboard-mcp.com을 추천하며, MCP 호환 도구의 성장하는 생태계를 강조합니다.

brumar는 유사한 프로젝트인 whiteboard-agents를 출시했으며, 이는 구현 아이디어를 검토하고 drawgent의 Excalidraw 및 다중 에이전트 지원에 대한 초점과 대조하는 데 유용합니다.

ramoz는 HTML 기반 화이트보드가 Excalidraw와 같은 JSON 중심 형식보다 에이전트에게 더 풍부한 의미론을 제공할 수 있다고 주장하지만, drawgent는 이미 LLM이 Excalidraw의 JSON 모델을 효과적으로 조작할 수 있음을 입증하고 있습니다.

주의해야 할 제한 사항

Chrome 의존성 – 현재 렌더러는 Chrome/Chromium 바이너리에 의존합니다. 네이티브 렌더러가 계획되어 있으나 아직 사용할 수 없습니다.
Claude 연결 모델 – Claude Code는 공개 주입 API가 없기 때문에, drawgent는 각 캔버스 연결마다 새로운 Claude 세션을 포크합니다.
Codex 실시간 연결 – 구현되었으나 작성 시점에 로그인된 Codex 계정으로 완전히 테스트되지는 않았습니다.
워크스페이스당 단일 장면 – 하나의 실시간 캔버스와 하나의 .excalidraw 파일만 지원됩니다. 이미지나 기타 에셋은 동기화되지 않습니다.

참여 방법

테스트 스위트 실행 – cargo test는 분수 인덱스와 방 암호화를 다룹니다. Node 스크립트(smoke.mjs, e2e-browser.mjs 등)는 캔버스 상호작용을 종단간 검증합니다.
기여 – 저장소는 주로 Rust(코드의 약 77%)로 구성되어 있으며 작은 JavaScript/HTML 프론트엔드가 있습니다. 네이티브 렌더링, 다중 장면 지원 또는 더 넓은 MCP 호환성 관련 이슈가 좋은 시작점입니다.
워크플로우 공유 – 커뮤니티 멤버들은 이미 대체 화이트보드 도구, Mermaid 기반 플러그인 및 사용자 지정 MCP 서버를 게시했습니다. 구체적인 사용 사례를 공유하면 프로젝트가 성숙해지는 데 도움이 됩니다.