Canvas Mode
Canvas Mode lays out every terminal you have open on one zoomable map. Each pane is a box (a node), the panes of a tab sit together in a frame (a group), and lines (connections) show which terminal started which. It's built for the moment you have a dozen agents running and can no longer tell from the tab strip which one is waiting for you.
Canvas is a tab like any other. Your other tabs keep running behind it, and switching away doesn't stop anything.
Opening and Leaving Canvas
- Click + in the tab strip and choose Canvas, or
- press
Ctrl+Shift+Alt+Space(the Toggle Canvas Mode shortcut).
There is only ever one Canvas tab. Opening it again jumps to the existing one and moves it to the front of the tab strip.
To leave, press the same shortcut (it takes you back to the tab you came from), click another tab, or close the Canvas tab.
What You See
| On the canvas | What it is |
|---|---|
| Node | One terminal pane. The header shows its title and, when known, the tab it belongs to, the shell, any armed automation, and the agent running in it (hover for "Agent running: …"). |
| Group | One tab, drawn as a frame around its panes. An empty tab can stay on the canvas as an empty frame you can drop terminals into. |
| Connection | An arrow from one terminal to another. Blue lines are ones you drew. Orange dashed lines were made by an agent or script, for example when an MCP agent opens a terminal for a sub-task. |
How much of a terminal you see depends on how far you've zoomed out. Close up, a node is the live terminal. Further out it becomes a still, uncoloured snapshot of the screen, then just its title, and at the furthest zoom each group shrinks to a chip showing its name, terminal count, armed automations and whether anything is running.
Hovering a node highlights its connections. A minimap in the corner shows where you are, and terminals that are running off screen get a small marker at the edge you can click to fly to them.
Moving Around
| To do this | Do this |
|---|---|
| Pan | Drag empty space, hold Space and drag anywhere, or use the arrow keys. |
| Zoom | Mouse wheel (zooms around the pointer), the − / + toolbar buttons, or Ctrl+= / Ctrl+-. |
| See everything | View All in the toolbar, or Shift+1. |
| Fit one tab's group | Shift+2 (the selected node's group, or the one nearest the centre). |
| Reset to 1:1 | Ctrl+0 |
| Step through terminals | Tab / Shift+Tab, in reading order group by group. |
If you'd rather the wheel scroll the canvas, change Settings → Terminal Behavior → Mouse wheel in Canvas Mode to Wheel scrolls the canvas, Ctrl+wheel zooms. In that mode Shift+wheel scrolls sideways.
Working With a Terminal
Double-click a node to enlarge it to nearly full screen and type into it. Click outside it, or press Ctrl+Shift+E, to shrink it back. Esc goes to the terminal program, not to Canvas, so it won't close the enlarged view.
From the node header or its right-click menu you can also:
- Hide from the canvas (and Show on the canvas). The terminal keeps running; it just isn't drawn.
- Open in its tab, which switches to the normal tab view with that pane focused.
- Close Terminal.
- Use the Automations section to see armed rules, or start a New automation for this terminal. See Automations.
Arranging the Canvas
- Drag a terminal by its header to move it.
- Drop a terminal inside another group's frame to move it to that tab. The pane really moves.
- Drag a group's label to move the whole tab. All its terminals, hidden ones included, move with it.
- To rename a tab, right-click its group and choose Rename Group…, or double-click the group heading in the terminal list.
- Arrange (or
A) tidies up: it puts each group's terminals in a grid and then lines up the groups. It only runs when you ask. - Dynamic Spacing tightens the gaps between nodes as you zoom in. It's off by default and doesn't change the saved positions.
Nodes can be moved but not resized.
Connections
Hover or select a node to see its connection ports.
- Drag from a port to another node to connect them.
- Click a port without dragging to get Connect a new terminal. Pick a shell profile and TermFlow opens a new terminal next to it, already connected and enlarged.
- Right-click empty canvas and choose New terminal here to open one at that spot.
- Right-click a connection to Label Connection… or Delete Connection. You can also click a connection to select it, then press
DeleteorBackspace, or drag one of its ends onto a different terminal.
Agents create connections too. When an MCP agent running in a TermFlow terminal calls create_terminal, the new terminal is connected to the agent's own terminal unless the agent passes connectToCaller: false.
The Terminal List and Filters
List (or L) opens a sidebar listing every terminal by tab. Type in Search terminals to filter by title; click a row to fly to that terminal, double-click it to rename. You can drag rows between groups and drag the sidebar's edge to resize it.
The toolbar has three filters:
| Button | What it does |
|---|---|
| Hidden (n) | Temporarily shows hidden terminals as faded outlines. Click again to hide them. |
| Main only (n) | Hides terminals that were opened by the API or MCP, so you can see just your own. It only changes what's drawn. |
| Close Ended | Closes every terminal whose program has exited. |
Canvas Shortcuts
These work while Canvas has the keyboard. While you're typing in an enlarged terminal, plain letter keys go to the terminal and only the Ctrl combinations act on Canvas.
| Action | Default |
|---|---|
| Toggle Canvas Mode | Ctrl+Shift+Alt+Space |
| Open Node in Its Tab | T (Ctrl+T while typing in a terminal) |
| Enlarge Node | E |
| Leave Terminal / Shrink Overlay | Ctrl+Shift+E |
| Arrange | A |
| Toggle Terminal List | L |
You can change these in Settings → Shortcuts. The navigation keys (Shift+1, Shift+2, Tab, the arrows, Space+drag, Ctrl+=/Ctrl+-/Ctrl+0, Delete) are fixed for now. On macOS, Cmd works wherever Ctrl is listed.
What Canvas Remembers
Node and group positions, your zoom and position, the sidebar, which terminals are hidden, Dynamic Spacing and Main only are saved with your session, per window, and come back after a restart. Positions for terminals that didn't survive the restart are dropped. Connections are stored separately and come back with the terminals they join.
Closing a terminal yourself deletes its connections. A terminal whose program merely exits keeps them.
Saved layouts don't include Canvas positions.
Canvas Over the API
Connections can be read and changed over the REST API:
| Method and path | Purpose |
|---|---|
GET /api/canvas/graph | Every node, group and connection. |
POST /api/canvas/edges | Create a connection: { "from", "to", "label"?, "origin"? }. origin is user or agent (default user). Creating the same direction twice does nothing. |
PATCH /api/canvas/edges/:id | Set or clear a connection's label. |
DELETE /api/canvas/edges/:id | Delete a connection. |
GET /api/terminals/:id/connections | A terminal's incoming and outgoing connections. |
POST /api/terminals with a parentTerminalId creates the terminal and an agent connection from the parent in one call.
An honest note: A few rough edges remain. Mouse clicks inside a terminal that's drawn smaller than its real size can land on the wrong cell, so enlarge a terminal before clicking into it (the keyboard always works). An enlarged split pane keeps its pane's size rather than growing. If you resize the app window while Canvas is open, terminals keep their old size until you leave Canvas and come back. And if a connection can't be saved, Canvas doesn't show an error; the line just doesn't appear.
Next Steps
- Automations: react to what your terminals print.
- Split panes: the normal tab view of the same terminals.