Excalidraw 캔버스가 코딩 에이전트의 작업대가 된다: Drawgent 살펴보기
한눈에 보는 요약
Drawgent는 이미 설치해 쓰고 있는 코딩 에이전트(Claude Code, Codex, opencode)를 Excalidraw 캔버스에 그대로 연결해 주는 도구입니다. 에이전트가 캔버스의 스크린샷과 장면 데이터를 직접 보고, 도형을 편집한 뒤 결과를 스스로 확인합니다.
핵심만 정리하면 이렇습니다.
- 에이전트를 번들로 제공하지 않습니다. 사용자의 설치 환경·로그인·설정·저장소를 그대로 활용합니다.
- 지시 전달 방법이 세 가지입니다: 오른쪽 채팅 패널, 도형 옆의
AGENT:메모, Excalidraw 레이저 도구로 표시한 영역. - Excalidraw 공동 작업 방에
🤖 Agent로 참여하므로, excalidraw.com에 머문 채로 작업을 요청하고 결과를 실시간으로 볼 수 있습니다. - 아직 Chrome이 필수이고, 작업 공간당 장면은 하나뿐이며 이미지와 파일은 동기화되지 않습니다.
기존 에이전트를 그대로 붙인다
요즘 "AI 다이어그램 도구"는 대부분 자체 모델이나 자체 에이전트를 끼워 파는 방식입니다. Drawgent는 반대 방향을 택했습니다. 이미 여러분이 로그인해 쓰고 있는 CLI를 연결 대상으로만 삼습니다.
- 지원 대상: Claude Code, Codex, opencode (사전 설치 및 로그인 필요)
- Claude Code와 Codex 연결에는 Node.js 18 이상이 추가로 필요합니다.
- 새 세션은 현재 디렉터리를 작업 공간으로 삼아 ACP(Agent Client Protocol)로 실행됩니다.
- 로컬 편집기와 API는 기본적으로
127.0.0.1:7300에서 뜨고, 포트가 사용 중이면 다음 빈 포트를 잡습니다. - 헤드리스 환경이라면 브라우저를 열지 못하는 대신 SSH 포트 포워딩 명령을 출력해 줍니다.
- 장면은
.drawgent/scene.json에 저장되며, 이 파일은 자동으로 Git 추적에서 제외됩니다.
에이전트의 작업 루프도 명확합니다. 스크린샷과 장면 데이터 확인 → 캔버스 실시간 편집 → 결과 점검 → 처리한 메모를 DONE으로 변경.
초기 설정과 기존 세션 연결
초기 설정 단계에서 에이전트 CLI, 로그인 상태, ACP 연결, 캔버스 도구, 렌더러를 차례로 점검합니다. 빠진 항목이 있으면 두루뭉술한 오류가 아니라 구체적인 해결 방법을 안내합니다. 반대로 설정이 성공하지 않았거나 설정 당시 확인한 구성 요소가 사라졌다면 실행 자체를 거부합니다.
ACP 연결 방식은 에이전트별로 조금씩 다릅니다.
- opencode: ACP를 직접 지원합니다.
- Claude Code / Codex: 공식 ACP 어댑터를 사용하되, 어댑터에 포함된 에이전트 바이너리는 설치하지 않고 사용자의 CLI에 연결합니다.
기존 세션에 붙이는 방법도 흥미롭습니다. 발견한 세션 목록에서 고르거나 ID를 직접 지정하면 되고, 현재 디렉터리의 세션을 먼저 보여 줍니다.
| 에이전트 | 기존 세션 연결 방식 |
| --- | --- |
| Claude Code | 대화형·백그라운드 세션을 검색해 전체 대화를 이어받은 새 세션을 ACP로 분기 실행. 기존 터미널 세션은 건드리지 않음 |
| opencode | 로컬 서버의 실행 중인 세션에 메시지를 전달하고 MCP 도구를 실행 중에 추가. TUI에서 입력한 프롬프트까지 채팅 패널에 반영 |
| Codex | 저장된 세션을 검색해 codex queue --thread <id>로 메시지를 전달하고, 세션 기록 파일에서 응답을 가져옴 |
Claude Code가 "분기" 방식인 이유는 명확합니다. 실행 중인 터미널 세션으로 메시지를 주입하는 공개 방식이 없기 때문입니다. Codex를 쓸 경우에는 설정 과정에서 등록한 Drawgent MCP가 Codex 시작 시점에 로드되어 있어야 합니다.
렌더러는 Chrome/Chromium이 있으면 그것을 쓰고, 없으면 Chrome Headless Shell 다운로드나 패키지 관리자 설치를 안내합니다.
지시를 전달하는 세 가지 방법
이 부분이 Drawgent의 가장 재미있는 지점입니다.
1. 채팅 패널
오른쪽 패널에서 요청을 보내고 응답과 도구 호출을 스트리밍으로 확인합니다. 권한 요청을 승인하거나 Stop으로 현재 턴을 취소할 수 있습니다.
2. 캔버스 메모 (AGENT:)
도형 옆이나 안에 AGENT:로 시작하는 텍스트를 쓰거나, 메모에서 도형으로 화살표를 그으면 작업 요청이 됩니다.
- 입력을 멈춘 뒤 약 2.5초 후, 메모의 위치·가리키는 대상·주변 요소와 함께 요청이 전달됩니다.
- 처리가 끝나면 초록색
DONE: …메모로 바뀝니다. 다시AGENT:로 수정하면 재전송됩니다.
3. 레이저 영역 (K)
Excalidraw의 레이저 도구로 영역을 둘러싸거나 그 위에 선을 그으면 빨간 윤곽선이 남고, 지시를 입력할 채팅 패널이 열립니다.
- 패널에 영역 아래에 있는 요소 목록이 표시되고, 다음 메시지에 영역 경계와 포함된 요소가 함께 전달됩니다.
- 4초 이내에 이어 그린 선들은 하나의 영역으로 묶입니다.
- 작업이 끝나면 흔적이 사라지고,
×로 선택 영역을 버릴 수 있습니다.
요청은 대기열에서 하나씩 실행되며, 대기 중인 메모가 이미 처리됐다면 건너뜁니다.
공동 작업 방: excalidraw.com에서 그대로 쓰기
에이전트가 Excalidraw 공동 작업 방에 🤖 Agent라는 참여자로 접속합니다. 에이전트 커서가 편집 위치를 따라 움직이기 때문에, 어디를 고치고 있는지 눈으로 보입니다.
- 사용자는 excalidraw.com에서 작성한
AGENT:메모로 작업을 요청하고 수정 결과를 실시간으로 확인합니다. - 로컬 편집기에도 방 상태가 반영되며, 채팅 패널은 계속 사용할 수 있습니다.
- 통신은 방 키를 이용한 종단 간 암호화를 적용합니다.
- 빈 방은 Excalidraw의 Firestore 저장소에서 불러오고 그곳에 저장합니다.
캔버스 도구(MCP)와 HTTP API
MCP 도구로 장면·스크린샷 조회, 요소 추가/수정/삭제, 캔버스 초기화, 지시 목록 조회와 완료 처리, 상태 설정을 지원합니다. 다이어그램 품질에 직결되는 세부 기능들이 눈에 띕니다.
get_screenshot:element_ids로 특정 요소를 확대해서 볼 수 있습니다.add_elements: Excalidraw 스켈레톤을 사용하며, 화살표를 ID로 연결하고 도형 경계 사이로 경로를 잡습니다.add_mermaid: 자동 배치를 지원합니다.update_elements: 도형을 옮기면 레이블과 연결된 화살표 경로를 함께 갱신합니다.
stdio MCP 서버는 실행 중인 Drawgent 서버를 자동으로 찾고, 저수준 서버는 설정된 에이전트나 별도 명령으로 지정한 ACP 에이전트를 연결할 수 있습니다. HTTP API는 상태 확인, 장면·스크린샷 조회, 요소 조작, Mermaid 추가, 캔버스 초기화, 지시 조회와 완료 처리, 상태 및 채팅 전송을 지원하고, WS /ws가 브라우저 동기화와 채팅 이벤트를 처리합니다.
권한 정책도 챙겨 두었습니다. 기본값은 그림 도구만 자동 승인이고, 나머지 작업은 채팅 패널에서 승인을 요청합니다. 승인 정책 변경과 API Bearer 토큰 설정도 가능합니다.
Docker 구성은 Drawgent와 Chromium만 포함한 캔버스 서버를 띄워, 공유 캔버스나 서버 측 공동 작업 방 브리지로 쓸 수 있습니다. 이때도 에이전트는 컨테이너에 번들되지 않고 항상 사용자의 기존 환경에서 실행됩니다.
구현과 한계
구현 쪽은 이렇게 구성되어 있습니다.
- Rust 서버가 세션 검색, ACP 및 실시간 연결, 요청 라우팅, 장면 저장과 편집, MCP, Excalidraw 방 연결을 담당합니다.
- 렌더러는 CDP를 통해 Chrome을 제어합니다.
- 웹 편집기와 렌더러 페이지는 빌드 후 바이너리에 내장됩니다.
- 테스트는 분수 인덱스, 방 암호화와 프레이밍, 채팅 및
AGENT:메모, 실제 브라우저 입력, Excalidraw 방 양방향 동기화, 레이저 영역 편집을 다룹니다.
도입을 고민한다면 아래 한계를 먼저 확인하세요.
- Chrome 렌더러가 필수입니다. 네이티브 렌더러는 아직 계획 단계입니다.
- Claude Code는 실행 중인 터미널 세션에 메시지를 주입할 공개 방식이 없어 새 세션으로 분기합니다.
- Codex 실시간 연결은 구현됐지만, 로그인한 Codex를 대상으로 한 테스트는 아직 거치지 않았습니다.
- 작업 공간당 장면 하나만 지원합니다.
- 이미지와 파일은 동기화하지 않습니다.
정리하며
Drawgent가 던지는 메시지는 "캔버스에도 AI를 넣자"가 아니라, **"이미 쓰는 코딩 에이전트에게 캔버스를 눈과 손으로 내주자"**에 가깝습니다. 아키텍처 다이어그램을 그려 놓고 도형 옆에 AGENT: 메모 한 줄을 남기는 것만으로 수정이 진행되는 워크플로는, 터미널과 그림 도구를 번갈아 오가던 기존 방식과 결이 다릅니다.
다만 Chrome 의존, 단일 장면 제약, 미검증 상태인 Codex 실시간 연결은 분명한 초기 단계 신호입니다. 지금은 다이어그램 중심으로 설계 문서를 다루는 팀이 실험해 볼 만한 도구로 보는 편이 적절해 보입니다.