agent-canvas

Agent Canvas

図やビジュアライゼーションを作成するために、Excalidraw キャンバスを操作する CLI ツールです。

インストール

使用する前に、CLI がインストールされているか確認します。

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

• インストールされていない場合：ユーザーに希望するパッケージマネージャー（bun または npm）を尋ねてから、インストールします。

  bun add -g @agent-canvas/[email protected]
  # or
  npm install -g @agent-canvas/[email protected]
  

• インストール済みだが、バージョンが 0.13.0 と異なる場合：同じパッケージマネージャーを使ってアップグレードします。

  • パスに .bun が含まれる場合 → bun add -g @agent-canvas/[email protected]
  • それ以外の場合 → npm install -g @agent-canvas/[email protected]

• インストール／アップグレード後：agent-canvas --version でバージョンが 0.13.0 であることを確認します。

クイックスタート

1. キャンバスを起動します（ブラウザーで開きます）。

   agent-canvas start &
   

2. CLI コマンドを使ってキャンバスに描画します。

ポートの設定

デフォルトのポートは 39820（WebSocket）と 39821（HTTP）です。ポートが競合する場合は、次の方法で設定します。

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

設定は ~/.agent-canvas/config.json に保存されます。start を使うと、一度限りの上書きができます。

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

優先順位：--port フラグ ＞ 環境変数 AGENT_CANVAS_WS_PORT ＞ 設定ファイル ＞ デフォルト値。

コマンドリファレンス

キャンバスの起動

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

ファイルの読み込み

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

ファイルから読み込む場合：ファイルパスを覚えておき、agent-canvas save <original-file> を使って同じファイルに保存します。

キャンバスの管理

キャンバスは複数に対応しています。各キャンバスは個別に保存され、切り替えて使用できます。

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

フォルダーの管理 — キャンバスをフォルダーに整理します。

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

注意：

• キャンバス名では大文字と小文字が区別されず、名前は一意である必要があります。
• キャンバスを削除するには UI を使います（サイドバーのキャンバスにカーソルを合わせ、「...」メニューをクリックします）。
• 各キャンバスには独自のシーンデータがあります。切り替えると、現在のキャンバスは自動的に保存されます。
• フォルダーを削除しても、その中のキャンバスは削除されません。キャンバスはフォルダーに属さない状態になります。

テキストの追加

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

• オプション：--font-size <size>、--text-align <left|center|right>、-a/--anchor <anchor>、--stroke-color <hex>、-n/--note <text>

• フォントサイズ：S=16、M=20（デフォルト）、L=28、XL=36

• アンカー（-a）：テキストのサイズは描画されるまでわからないため、アンカーを使うと、テキストのバウンディングボックス上のどの点を（--ax、--ay）に合わせるか指定して、正確に位置を調整できます。デフォルト：bottomLeft。

  アンカー	一般的なテキストの種類
  topLeft	バッジ、タグ、アイコンのラベル
  topCenter	サブタイトル、図形の下に置く説明
  topRight	タイムスタンプ、バージョン、ステータス
  leftCenter	横の注釈（図形の右側）
  center	中央揃えのタイトル、メインラベル
  rightCenter	横の注釈（図形の左側）
  bottomLeft	脚注、メモ
  bottomCenter	タイトル、図形の上に置く見出し
  bottomRight	脚注、署名

• 戻り値：Text created (id: <id>, x: <x>, y: <y>, <width>x<height>) — 正確なレイアウトに使える、実際の左上位置と寸法です。

描画要素の追加

すべての描画コマンドで、共通のスタイルオプションを使用できます。

• 線：--stroke-color <hex>（デフォルト：#1e1e1e）、--stroke-width <1-4>（デフォルト：2）、--stroke-style <solid|dashed|dotted>（デフォルト：solid）
• 塗りつぶし（図形のみ）：--background-color <hex>（デフォルト：透明）、--fill-style <solid|hachure|cross-hatch>（デフォルト：solid）
• メタ情報：-n/--note <text> — 要素の意味を説明します。積極的に使用してください。後で読み返すときに、メモがあると図の意図を理解しやすくなります。
• アニメーション：--animated — 新しく追加した要素が表示されるよう、ビューポートを自動スクロールします。小さな要素はズームインし、大きな要素はズームアウトし、通常サイズの要素では最小限のスクロールを行います。

推奨カラー（Excalidraw パレットより）：

色	線（濃色）	背景（淡色）
赤	#e03131	#ffc9c9
青	#1971c2	#a5d8ff
緑	#2f9e44	#b2f2bb
黄	#f08c00	#ffec99
シアン	#0c8599	#99e9f2
バイオレット	#6741d9	#b197fc
グレー	#495057	#dee2e6

形状

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

• タイプ：rectangle、ellipse、diamond
• -l/--label を使用して形状内にテキストを追加します（デフォルトの fontSize は 16）。調整するには --label-font-size <n> を使用します
• ラベルの色はデフォルトで --stroke-color を継承します。上書きするには --label-stroke-color <hex> を使用します
• 戻り値：Shape created (id: <id> x=<x> y=<y> w=<width> h=<height>) — ラベルに合わせて自動サイズ調整された後の実際の寸法

⚠️ ラベルのサイズ設定 — 重要：描画前に計算してください

形状が小さすぎると、Excalidraw が自動的に拡張するため、矢印の座標がずれてしまいます。必ず次の操作を行ってください。

1. 以下の数式を使って最小寸法を計算します
2. 計算した値をそのまま使用します — 絶対に推測したり、小さい値を使ったりしないでください

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

例：楕円内のラベル「Message Queue」（13 文字）

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)

ヒント：長いラベルの場合は、手動で \n を挿入してから、更新した lineCount で再計算します。

線と矢印

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>

• 矢印固有のオプション：--start-arrowhead、--end-arrowhead（arrow、bar、dot、triangle、diamond、none）

矢印の種類（--arrow-type）：

タイプ	説明	用途
sharp	直線（デフォルト）	直接的な接続
round	制御点のある曲線	自然な流れ、重なりの回避
elbow	直角（90°）の折れ曲がり	フローチャート、回路図

中間点（--via）： --via を使用して、絶対座標で中間点を "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"

ヒント：

• round の場合：曲線は制御点（直線経路からオフセットされた点）の方向に曲がります
• elbow の場合：点は 90° 経路の角を定義します

ポリゴン

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

画像

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

• 対応形式：PNG、JPEG、GIF、SVG、WebP
• 幅と高さのデフォルトは元の画像の寸法です。縦横比を保って拡大縮小するには、どちらか一方を指定します
• 画像データはキャンバスに Base64 として埋め込まれます（ブラウザーの IndexedDB に保存）
• 戻り値：Image added (id: <id>, x: <x>, y: <y>, <width>x<height>)

要素を操作する

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）： 要素（rectangle、ellipse、diamond、image）の辺を拡大または縮小します。値は要素のローカル座標系で指定します（回転を考慮します）。

例：

# 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

シーンを読み取る

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 出力の構造：

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 は、ラベルの id に対応します
• via は、--via の入力と同じ形式で中間点を示します（"x1,y1;x2,y2"。中間点がない場合は null）
• --with-style は stroke、bg フィールドを追加します
• --json は Excalidraw の完全な形式を返します（特定の要素を検索するには jq と併用します）

保存、エクスポート、クリア

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!

注意：clear を実行する前に、現在のキャンバスを先に保存またはエクスポートするか、ユーザーに確認してください。 ⚠️必ず agent-canvas clear ではなく agent-canvas new を優先してください。clear を使用するのは、ユーザーの確認後に限ります！⚠️

設計思想

あなたは完璧主義者です。少しでもずれて見えたら、実際にずれています。修正してください。

基本原則：一貫性が意味を表します。

• 同じ関係 → 同じ配置と間隔

  • 同じ関係にある要素は、同じ位置に揃えます
  • 同じ階層の要素間の間隔は、すべて同じにします
  • 精度を高めるため、グリッド（例：10px 単位）に合わせます

• 同じ種類 → 同じ色とサイズ

  • 同じ種類のノードは、寸法を揃えます
  • 同じ色は同じ意味を表します。色は最大 3〜4 色にし、少ないほど効果的です
  • 重要な要素は大きくします

• 細部が重要です

  • 矢印は形状の辺に正確につなげます
  • export で確認し、わずかな不備も修正します

必読ガイド

1. 座標：原点（0,0）は左上です。X→右、Y→下です。色は16進数（#FF5733）または transparent で指定します。

2. ワークフロー：キャンバスを読み取る → レイアウトを計画する → 図形を描く → 矢印／線を追加する（必要な場合）→ 調整する。

   • 重要：キャンバスの内容はブラウザーの localStorage に自動保存されます。描画する前に、必ず agent-canvas read を実行し、既存の内容を確認してください。
   • 古い内容がある場合は、（a）編集を続ける、（b）クリアして新しく始める、（c）先に保存／エクスポートしてからクリアする、のどれにするかユーザーに尋ねてください。
   • 図形でレイアウトを定義し、正確な座標を指定します。
   • 矢印の端点は図形の位置によって決まるため、先に矢印を描くと位置がずれます。
   • 調整：最初の下書きの後、read と export を実行して確認します。デザイン方針に照らし合わせて確認してください。
     • 配置に問題がある場合 → move-elements でグリッドに合わせます。
     • 間隔が不均一な場合 → move-elements で間隔を均等にします。
     • 要素が重なっている場合 → move-elements を使うか、delete-elements で削除して描き直します。
     • サイズが適切でない場合 → delete-elements で削除して描き直します。
     • 矢印の位置がずれている場合 → delete-elements で削除し、端点を正しく指定して描き直します。
     • コンテナーのサイズに問題がある場合 → resize-elements で適切なサイズに調整します。

3. キャンバスの段階的な読み取り：

   • read - まずここから始めます。コンパクトな TOON 形式（JSON の約7%のサイズ）
   • read --with-style - スタイルが重要な場合は色の情報を追加します。
   • export -o canvas.png + 画像を表示 - 視覚的／空間的な理解に使用します。
   • read --json | jq '.elements[] | select(.id=="<id>")' - 特定の要素の詳細を取得します。

4. コマンドの一括実行：効率化のため && で連結します。描画コマンドに Bash のコメントを書かないでください。

   agent-canvas add-shape -t rectangle -x 100 -y 100 -l "A" && \
   agent-canvas add-shape -t rectangle -x 300 -y 100 -l "B" && \
   agent-canvas add-arrow -x 220 -y 130 --end-x 300 --end-y 130
   

描画チュートリアル

描画する前に、図の種類を特定し、チュートリアルがあるか確認してください。

1. ユーザーが希望する図の種類（フローチャート、アーキテクチャ図、マインドマップ、UI モックアップなど）を特定します。
2. references/REFERENCE.md を読みます。ここには、利用可能なすべての図のチュートリアルを掲載したチュートリアル索引があります。
3. 該当するチュートリアルがある場合：描画する前に、まず該当するチュートリアルを読みます。チュートリアルには、図の種類ごとのルール、レイアウトパターン、ベストプラクティスが記載されています。
4. 描画時にチュートリアルのガイドラインを適用します。