Collaborate with Pi through editable Excalidraw drawings in a local browser canvas.
Use in Pi
Run /canvas open to open local canvas and enable canvas tools for current agent.
Draw normally, then pause briefly to send a coalesced drawing observation to Pi.
Each observation includes scene metadata, text objects, and an image of the current visible viewport.
New observations appear as compact Pi notifications; full metadata and images reach the agent through hidden session messages instead of filling the visible message list.
Viewport images preserve pan and zoom, exclude off-screen content and editor controls, and never move your selection or viewport.
Images are bounded to 1024 pixels on the longest edge and 256 KiB of base64 data.
Pi communicates visually first through native text, notes, arrows, highlights, and other drawing elements.
These are ordinary editable shapes, not separate comments or threads.
Textual assistant replies are a last resort when visual communication is unsuitable or blocked.
Only actual assistant messages update the quiet notification icon beside sharing status, including on mobile.
Open it to read the latest reply; opening clears its unread dot, and a new reply lights it again.
Long replies wrap and scroll inside the notification sidebar.
No automatic canvas notification popups appear.
The Excalidraw Pi menu group appears only when an actual assistant reply is available.
Persistent sharing status shows connection and whether your drawing is shared with Pi.
Canvas tools activate only in drawing mode; ordinary coding tools remain available.
Download drawing saves the native Excalidraw scene, including Pi's visual contributions.
Pi drawing commits create one native undo step and reject stale or conflicting changes.
Stale draws require fresh inspection and reassessed placement before one retry.
A blocked or abandoned contribution requires an actual assistant reply explaining why, not silent abandonment.
Run /canvas close to disable canvas tools and close local server.
Drawings and assistant conversation belong to the current Pi session branch.
Restoring a branch discards pending proposals.
Limits and privacy
Proposals support shape additions, style changes, and unbound deletions.
Edit existing geometry or text manually; images are unsupported.
Scenes support ≤1000 elements and 512 KiB serialized data.
Concurrent tabs cannot silently overwrite each other's edits.
On conflict, Not shared with Pi explains that your latest edits remain in this browser tab and are not reaching the agent.
Visible recovery actions are Keep my drawing, Use shared drawing, and Save copy.
Keep my drawing replaces the shared scene; Use shared drawing discards this tab's unsaved edits.
Both require an inline confirmation that is revalidated against the latest scene before changing either drawing.
Save copy downloads the current local scene without resolving the conflict.
Temporary sharing failures and dropped event streams retry up to three times automatically.
After stream retries stop, Reconnect restarts the connection.
Leaving with unsaved edits still triggers the browser's data-loss warning; normal drawing and recovery do not use browser dialogs.
Canvas binds only loopback address.
Treat its access URL as private; token moves from URL fragment into tab-local session storage.
Browser assets and fonts are served locally; CSP blocks Excalidraw's upstream CDN fallback.
Viewport images are sent to the main Pi agent's configured model provider alongside drawing observations; visual interpretation requires an image-capable model.
Images are not included in canvas snapshots or browser state streams, but hidden observation messages retain images in Pi session history.
Requests to model provider remain within main Pi agent, using its existing configuration.
<img src="assets/banner.svg" alt="canvas" height="70">
# canvas
Collaborate with Pi through editable Excalidraw drawings in a local browser canvas.
## Use in Pi
Run `/canvas open` to open local canvas and enable canvas tools for current agent.
Draw normally, then pause briefly to send a coalesced drawing observation to Pi.
Each observation includes scene metadata, text objects, and an image of the current visible viewport.
New observations appear as compact Pi notifications; full metadata and images reach the agent through hidden session messages instead of filling the visible message list.
Viewport images preserve pan and zoom, exclude off-screen content and editor controls, and never move your selection or viewport.
Images are bounded to 1024 pixels on the longest edge and 256 KiB of base64 data.
Pi communicates visually first through native text, notes, arrows, highlights, and other drawing elements.
These are ordinary editable shapes, not separate comments or threads.
Textual assistant replies are a last resort when visual communication is unsuitable or blocked.
Only actual assistant messages update the quiet notification icon beside sharing status, including on mobile.
Open it to read the latest reply; opening clears its unread dot, and a new reply lights it again.
Long replies wrap and scroll inside the notification sidebar.
No automatic canvas notification popups appear.
The Excalidraw Pi menu group appears only when an actual assistant reply is available.
Persistent sharing status shows connection and whether your drawing is shared with Pi.
Canvas tools activate only in drawing mode; ordinary coding tools remain available.
**Download drawing** saves the native Excalidraw scene, including Pi's visual contributions.
Pi drawing commits create one native undo step and reject stale or conflicting changes.
Stale draws require fresh inspection and reassessed placement before one retry.
A blocked or abandoned contribution requires an actual assistant reply explaining why, not silent abandonment.
Run `/canvas close` to disable canvas tools and close local server.
Drawings and assistant conversation belong to the current Pi session branch.
Restoring a branch discards pending proposals.
## Limits and privacy
Proposals support shape additions, style changes, and unbound deletions.
Edit existing geometry or text manually; images are unsupported.
Scenes support ≤1000 elements and 512 KiB serialized data.
Concurrent tabs cannot silently overwrite each other's edits.
On conflict, **Not shared with Pi** explains that your latest edits remain in this browser tab and are not reaching the agent.
Visible recovery actions are **Keep my drawing**, **Use shared drawing**, and **Save copy**.
Keep my drawing replaces the shared scene; Use shared drawing discards this tab's unsaved edits.
Both require an inline confirmation that is revalidated against the latest scene before changing either drawing.
Save copy downloads the current local scene without resolving the conflict.
Temporary sharing failures and dropped event streams retry up to three times automatically.
After stream retries stop, **Reconnect** restarts the connection.
Leaving with unsaved edits still triggers the browser's data-loss warning; normal drawing and recovery do not use browser dialogs.
Canvas binds only loopback address.
Treat its access URL as private; token moves from URL fragment into tab-local session storage.
Browser assets and fonts are served locally; CSP blocks Excalidraw's upstream CDN fallback.
Viewport images are sent to the main Pi agent's configured model provider alongside drawing observations; visual interpretation requires an image-capable model.
Images are not included in canvas snapshots or browser state streams, but hidden observation messages retain images in Pi session history.
Requests to model provider remain within main Pi agent, using its existing configuration.
[Installation](../../README.md#install)
<!-- config:start -->
### Commands
| Command | Purpose |
| --- | --- |
| `/canvas` | Open, close, or inspect drawing mode |
<!-- config:end -->
