Canvas View

A zoomable board where every agent is a live, interactive terminal card — watch them all at once, and broadcast one command to every selected agent.

Keywords:canvasboardcardsgridzoompanbroadcastmulti-selectselect allarrangeorganizetilefillexpand cardbird’s-eyeoverview of agents

Related: view-modes · shelf · terminal · active-agents · keyboard-shortcuts

What it is#

Canvas turns every open terminal tab into a card floating on an infinite, zoomable board. Each card is a live, fully interactive terminal — not a screenshot — so you can watch several agents work simultaneously, then click into any card to type. A card whose task just finished lights up so you can see at a glance who’s done.

Toggle Canvas: ⌘⌥↩ (toggle_canvas). Toggling has no effect if no worktrees are open.

The signature feature: broadcast to every agent#

Canvas lets you type a command once and send it to many agents at once:

1. Select multiple cards. ⌘-click cards to add them to the selection, or press ⌘⌥A (Select All Cards). With two or more selected, Canvas enters broadcasting mode (the toolbar shows “Broadcasting to N cards”).
2. Type into the primary (focused) card. What you type — text and submitted commands — is mirrored to every selected card.
3. Great for “run the tests”, “commit”, “/clear”, “continue”, etc. across a whole fleet of agents in one keystroke.

Selection controls:

• ⌘-click a card body → toggle it in/out of the selection.
• ⌘-click a terminal link → open it. Recognized links take priority over card multi-selection, including when ⌘ is held across repeated clicks.
• Click (without ⌘) an already-selected card → make it the primary (the one you type into) without deselecting the rest. (⌘-clicking a selected card instead removes it from the selection.)
• Click empty canvas → clear the selection. Esc also clears it while broadcasting (two or more cards selected).

Working with cards#

Arranging the board#

• ⌘⌥A Select All Cards — select every card (entering broadcast).
• ⌘⌥R Arrange Cards — bin-pack the existing cards to fit the viewport’s aspect ratio, preserving each card’s size, then fit-to-view.
• ⌘⌥G Organize Cards — reset every card to a uniform grid (≈√N columns) at a default size and center them.
• ⌘⌥T Tile Cards — resize every card to tile and fill the viewport, like an automatic window manager. Cards form a balanced grid whose orientation follows the window: a wide window spreads them into rows (2 cards → left/right, 5 → top 2 / bottom 3), a tall window stacks them into columns. Each line fills its full extent, so the cards use as much area as possible. The zoom adapts to card count: a few cards stay at native scale (large, detailed), while many cards zoom out so each keeps a readable terminal surface (more rows/columns at smaller text — enough to follow what each agent is doing).

These also appear as toolbar buttons. There’s a ? help popover (bottom-left) explaining pan/zoom/expand — hover the button to reveal it, move away to dismiss, or click to pin it open.

Toolbar actions#

The main toolbar tracks the focused card. Its center status area shows the same PR/check summary, toast, or time hint as Normal view, and the right-side Run Script / Custom Command buttons run against the focused card’s worktree. ⌘⌃G (open_pull_request, “Open on Code Host”) opens that card’s PR when it has one, or the repository page otherwise.

Visual cues#

• Focused card: bright accent border. Selected (multi-select): medium accent border. Unselected: faint border.
• Finished/unread task: the card title bar turns orange.
• During selection/broadcast, non-focused cards get a subtle shield overlay so you don’t accidentally type into the wrong one.
• The left nav band is tinted with the focused card’s repository color (windowTintMode).

Agent Island completion reminders#

Clicking an Agent Island Done reminder keeps the existing Canvas navigation: Prowl comes forward and focuses the target card and pane. The completion becomes read once that terminal is the actual keyboard responder in its key, visible window and some of the terminal intersects its visible viewport. A focused pane completely outside the viewport stays unread until navigation brings it back. Partial visibility is sufficient; no minimum visible percentage is required. A logical focus request alone, an inactive window, or a hidden/detached terminal does not count as viewing it. Other cards and splits are not acknowledged merely because they are selected or receive broadcast input. Blocked reminders remain until the agent leaves the blocked state.

Layout & sizing#

• Default card size adapts to screen width (roughly 800×550 on a 14”, larger on a 27”). Cards have generous min/max bounds and snap-animate on resize.
• On first entry, cards auto-arrange into a balanced grid. Positions, sizes, and z-order are persisted across launches (in UserDefaults) and restored when you return to Canvas.
• Closing a card’s last tab prunes it; focus advances to a neighbor.

Many agents at once#

Canvas is built for scale: the grid grows with the number of cards, Arrange packs them to your viewport, and you can zoom out to see everything then zoom into a region. Cards are real terminals, so the ones off-screen are occlusion-managed for performance.

Settings that affect Canvas#

• defaultViewMode — launch directly into Canvas.
• canvasDefaultLayout — how cards are first laid out when you open Canvas: uniform (same-size cards packed to fit) or tile (resize cards to fill the screen, the default). Only the initial auto-layout is affected; saved card positions are always restored.
• windowTintMode / repository colors — card and nav tinting.
• showRunButtonInToolbar — whether the Run button appears in the Canvas toolbar.

Keyboard card navigation#

⌘⌃↑ / ⌘⌃↓ / ⌘⌃← / ⌘⌃→ move focus to the nearest card in that direction, based on the 2D card positions on the board. If the target card is partially off-screen, the canvas pans smoothly to reveal it without changing the zoom level. These are the same key combos used for worktree/book navigation in Normal and Shelf views — in Canvas they switch to spatial navigation automatically.

When to recommend Canvas vs Shelf#

• Canvas = spatial, see-everything, broadcast to many. Best when you’re supervising a fleet or fanning the same command out.
• Shelf = linear, keyboard-fast triage of many worktrees one at a time.

See view-modes for the comparison.

Gotchas for agents#

• Broadcasting requires ≥2 selected cards; it mirrors what’s typed into the primary card.
• Toggling Canvas with nothing open is a no-op.
• A “card” maps to a tab, identified by tab.id — the same ID the prowl CLI uses.