🇺🇸English

Agent Canvas

A CLI tool to interact with an Excalidraw canvas for creating diagrams and visualizations.

Installation

Before using, check if CLI is installed:

which agent-canvas && agent-canvas --version

• If not installed : Ask the user which package manager they prefer (bun or npm), then install:

  bun add -g @agent-canvas/cli@0.13.0
  

  or

  npm install -g @agent-canvas/cli@0.13.0

• If installed but version differs from 0.13.0 : Upgrade using the same package manager:

  • Path contains .bun → bun add -g @agent-canvas/cli@0.13.0
  • Otherwise → npm install -g @agent-canvas/cli@0.13.0

• After install/upgrade : Verify with agent-canvas --version to confirm version is 0.13.0

Quick Start

1. Start the canvas (opens in browser):

   agent-canvas start &

2. Use CLI commands to draw on the canvas.

Port Configuration

Default ports: 39820 (WebSocket), 39821 (HTTP). If ports conflict, configure via:

agent-canvas config set port 39820         # Set WebSocket port
agent-canvas config set http-port 39821    # Set HTTP port
agent-canvas config list                   # Show all config (value + source)
agent-canvas config get port               # Show current port
agent-canvas config reset port             # Reset to default

Config is saved to ~/.agent-canvas/config.json. One-time override via start:

agent-canvas start --port 8000 --http-port 8001 &

Priority: --port flag > env var AGENT_CANVAS_WS_PORT > config file > default.

Commands Reference

Start Canvas

agent-canvas start &                  # Start server in the background (will close automatically when no action for a while)

Load File

agent-canvas load file.excalidraw     # Load .excalidraw file into current canvas

When loading from file : Remember the file path and save back to it with agent-canvas save <original-file>.

Canvas Management

The canvas supports multiple canvases. Each canvas is stored independently and can be switched between.

agent-canvas list                     # List all canvases ([U]=User active, [A]=Agent active, [F]=Folder)
agent-canvas new -n "Name" [--use]    # Create new canvas, optionally switch to it
agent-canvas use "Name"               # Switch to canvas by name
agent-canvas rename "New Name"        # Rename current canvas

Folder Management — Organize canvases into folders:

agent-canvas create-folder -n "Name"              # Create a new folder
agent-canvas delete-folder "Name"                  # Delete folder (canvases become ungrouped)
agent-canvas move-to-folder "Canvas" "Folder"      # Move canvas into a folder
agent-canvas move-to-folder "Canvas" --ungrouped   # Remove canvas from its folder

Notes:

• Canvas names are case-insensitive and must be unique
• Delete canvases via UI (hover over canvas in sidebar, click "..." menu)
• Each canvas has its own scene data; switching automatically saves current canvas
• Deleting a folder does NOT delete the canvases inside it — they become ungrouped

Add Text

agent-canvas add-text -t "<text>" --ax <x> --ay <y> [options]

• Options: --font-size <size>, --text-align <left|center|right>, -a/--anchor <anchor>, --stroke-color <hex>, -n/--note <text>

• Font sizes: S=16, M=20 (default), L=28, XL=36

• Anchor (-a): Since text size is unknown until rendered, anchor gives you precise positioning control by specifying which point of the text bounding box aligns to (--ax, --ay). Default: bottomLeft.

• Returns: Text created (id: <id>, x: <x>, y: <y>, <width>x<height>) — actual top-left position and dimensions for precise layout

Add Drawing Elements

All drawing commands share common style options:

• Stroke : --stroke-color <hex> (default: #1e1e1e), --stroke-width <1-4> (default: 2), --stroke-style <solid|dashed|dotted> (default: solid)
• Fill (shapes only): --background-color <hex> (default: transparent), --fill-style <solid|hachure|cross-hatch> (default: solid)
• Meta : -n/--note <text> - semantic description for the element. Use liberally - notes help understand diagram intent when reading back later.
• Animated : --animated - auto-scroll viewport to show the newly added element. Small elements zoom in, large elements zoom out, normal elements scroll minimally.

Recommended Colors (from Excalidraw palette):

Shapes

agent-canvas add-shape -t <type> -x <x> -y <y> [-w <width>] [-h <height>] [-l <label>]

• Types: rectangle, ellipse, diamond
• Use -l/--label to add text inside the shape (fontSize: 16 by default), --label-font-size <n> to adjust
• Label color inherits from --stroke-color by default; use --label-stroke-color <hex> to override
• Returns : Shape created (id: <id> x=<x> y=<y> w=<width> h=<height>) — actual dimensions after auto-sizing for labels

⚠️ Label Sizing - CRITICAL: Calculate BEFORE drawing

If shape size is too small, Excalidraw auto-expands, breaking arrow coordinates. You MUST:

1. Calculate minimum dimensions using the formulas below
2. Use the calculated values directly — NEVER estimate or use smaller values

Step 1: Calculate text dimensions (fontSize=16 by default)

  textWidth = charCount × fontSize × 0.6  (English/numbers)
  textWidth = charCount × fontSize        (CJK characters)
  textHeight = lineCount × fontSize × 1.35

Step 2: Calculate minimum shape size (use these values, not smaller!)
  rectangle: width = textWidth + 50,  height = textHeight + 50
  ellipse:   width = textWidth × 1.42 + 55,  height = textHeight × 1.42 + 55
  diamond:   width = textWidth × 2 + 60,  height = textHeight × 2 + 60

Example : Label "Message Queue" (13 chars) in ellipse

textWidth = 13 × 16 × 0.6 = 124.8
textHeight = 1 × 16 × 1.35 = 21.6
ellipse width = 124.8 × 1.42 + 55 = 232
ellipse height = 21.6 × 1.42 + 55 = 86
→ Use: -w 232 -h 86 (or round up to -w 240 -h 90)

Tip : For long labels, insert \n manually, then recalculate with updated lineCount.

Lines & Arrows

agent-canvas add-line -x <x1> -y <y1> --end-x <x2> --end-y <y2>
agent-canvas add-arrow -x <x1> -y <y1> --end-x <x2> --end-y <y2>

• Arrow-specific: --start-arrowhead, --end-arrowhead (arrow, bar, dot, triangle, diamond, none)

Arrow Types (--arrow-type):

Intermediate Points (--via): Use --via to specify intermediate points as absolute coordinates in format "x1,y1;x2,y2;...":

# Round arrow: one control point determines curve direction
# Vertical arrow curving left (control point at x=50, left of the line)
agent-canvas add-arrow -x 100 -y 100 --end-x 100 --end-y 300 --arrow-type round --via "50,200"

# Elbow arrow: multiple points for 90° turns
# Loop back pattern: down → left → up (for flowchart iterations)
agent-canvas add-arrow -x 175 -y 520 --end-x 175 --end-y 280 --arrow-type elbow --via "120,520;120,280"

Tips :

• For round: curve bends toward the control point (offset from straight path)
• For elbow: points define the corners of the 90° path

Polygon

agent-canvas add-polygon -p '[{"x":0,"y":0},{"x":100,"y":0},{"x":50,"y":100}]'

Image

agent-canvas add-image -f <path> -x <x> -y <y> [-w <width>] [-h <height>] [-n <note>]

• Supported formats: PNG, JPEG, GIF, SVG, WebP
• Width/height default to original image dimensions; specify one to scale proportionally
• Image data is embedded as base64 in the canvas (stored in browser IndexedDB)
• Returns : Image added (id: <id>, x: <x>, y: <y>, <width>x<height>)

Manipulate Elements

agent-canvas delete-elements -i <id1>,<id2>,...
agent-canvas rotate-elements -i <id1>,<id2>,... -a <degrees>
agent-canvas move-elements -i <id1>,<id2>,... --delta-x <dx> --delta-y <dy>
agent-canvas resize-elements -i <id1>,<id2>,... [--top <n>] [--bottom <n>] [--left <n>] [--right <n>]
agent-canvas group-elements -i <id1>,<id2>,...
agent-canvas ungroup-element -i <id>

Resize Elements (resize-elements): Expand or contract element edges (rectangle, ellipse, diamond, image). Values are in element's local coordinate system (respects rotation).

Examples:

# Expand bottom edge by 50px (increase height)
agent-canvas resize-elements -i abc123 --bottom 50

# Expand both right and bottom (like dragging bottom-right corner)
agent-canvas resize-elements -i abc123 --right 50 --bottom 30

# Contract left edge by 20px (decrease width)
agent-canvas resize-elements -i abc123 --left -20

# Expand all sides uniformly
agent-canvas resize-elements -i abc123 --top 25 --bottom 25 --left 25 --right 25

Read Scene

agent-canvas read                # TOON format (compact, ~7% of JSON size)
agent-canvas read --with-style   # Include stroke/bg colors
agent-canvas read --json         # Raw Excalidraw scene JSON

TOON output structure:

shapes[N]{id,type,x,y,w,h,angle,labelId,note}       # rectangle, ellipse, diamond, polygon
lines[N]{id,type,x,y,endX,endY,via,angle,note}      # line, arrow
labels[N]{id,containerId,content,x,y,w,h}           # text bound to shapes (via labelId)
texts[N]{id,content,x,y,w,h,angle,note}              # standalone text elements
groups[N]{id,elementIds}                             # element groupings

• labelId in shapes links to id in labels
• via shows intermediate points in same format as --via input ("x1,y1;x2,y2" or null if none)
• --with-style adds stroke, bg fields
• --json returns full Excalidraw format (use with jq to query specific elements)

Save, Export and Clear

agent-canvas save file.excalidraw
agent-canvas export -o out.png [--scale 2] [--dark] [--no-background]
agent-canvas clear                # Clear all elements from the canvas, use with caution!

Note : Before running clear, ask the user if they want to save or export the current canvas first. ⚠️ALWAYS prefer agent-canvas new over agent-canvas clear only use clear when user has confirmed!⚠️

Design Philosophy

You are a perfectionist. If it looks slightly off, it IS off. Fix it.

Core principle: Consistency reflects meaning.

• Same relationship → Same alignment & spacing

  • Elements with the same relationship should share identical alignment
  • Gaps between same-level elements should be equal throughout
  • Snap to grid (e.g., 10px units) for precision

• Same type → Same color & size

  • Same-type nodes share identical dimensions
  • Same color = same meaning; max 3-4 colors; less is more
  • Important elements = larger size

• Details matter

  • Arrows connect precisely to shape edges
  • Review via export and fix any imperfections

IMPERATIVE GUIDE

1. Coordinates : Origin (0,0) is top-left. X→right, Y→down. Colors in hex (#FF5733) or transparent.

2. Workflow : Read canvas → Plan layout → Draw shapes → Add arrows/lines(if necessary) → Adjust.

   • IMPORTANT : Canvas content is auto-saved to browser localStorage. Always run agent-canvas read first to check for existing content before drawing.
   • If old content exists, ask the user whether to: (a) continue editing, (b) clear and start fresh, or (c) save/export first then clear.
   • Shapes define the layout and provide exact coordinates
   • Arrow endpoints depend on shape positions — drawing arrows first leads to misalignment
   • Adjust : After initial draft, run read and export to review. Check against Design Philosophy:
     • Alignment issues? → move-elements to snap to grid

Drawing Tutorials

Before drawing, identify the diagram type and check for tutorials:

1. Determine what type of diagram the user wants (flowchart, architecture, mindmap, UI mockup, etc.)
2. Read references/REFERENCE.md — this is the tutorial index listing all available diagram tutorials
3. If a matching tutorial exists : Read the specific tutorial FIRST before drawing — tutorials contain type-specific rules, layout patterns, and best practices
4. Apply the tutorial guidelines while drawing

Weekly Installs

65

Repository

whq25/agent-canvas

GitHub Stars

11

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode52

gemini-cli48

codex48

claude-code47

cursor43

github-copilot35