AgentGridAgentGrid Docs
Core Concepts

The Canvas

Navigate and organize the infinite workspace where every AgentGrid pane lives.

Each space has an infinite 2D canvas. Agent panes, terminals, browsers, notes, and other tools can be arranged freely, while AgentGrid remembers the camera position and zoom for that space.

Panning and zooming

The defaults follow each platform and can be rebound in Settings.

  • Pan from anywhere - hold OptionCtrl, then drag, middle-click, or scroll. This works over live panes, including browsers.
  • Zoom under the cursor - CmdScrollCtrlScroll.
  • Trackpad zoom - pinch on any platform.
  • Zoom in or out - Cmd=Ctrl= / Cmd-Ctrl-, or CmdCtrl with the numeric keypad's plus and minus. These shortcuts zoom the focused Coordinator or Explorer first, then a maximized pane, and otherwise the canvas. Browser pages also forward shifted and numpad zoom shortcuts.
  • Reset zoom to 100% - Cmd0Ctrl0 or View → Reset Zoom resets the same focused target. The canvas view stays centred where you were.
  • Maximize the focused or selected pane - CmdShiftEnterCtrlShiftEnter or CtrlShift2CtrlShift2. Press it again or EscEsc to restore your previous view.
  • Pan with the keyboard - with nothing selected, the arrow keys pan the canvas. Hold ShiftShift for a bigger step.

Ordinary scrolling over an unfocused pane pans the canvas, even if that pane is selected. Click inside a pane to focus it and scroll its content. Browser pages and terminals whose apps capture mouse input keep their own scrolling behavior. Maximizing a pane focuses it.

Space is ordinary input, so it reaches terminals and editors instead of activating canvas pan.

Inside a browser pane, hold CtrlAlt while pinching to send the gesture to the page instead of zooming the canvas.

Spaces are tabs

A space owns its canvas, pane list, camera state, and project folder.

  • New space - CmdTCtrlT.
  • Switch space - click a tab or use the platform tab-navigation shortcut.
  • Reorder spaces - drag tabs left or right.
  • Close space - CmdWCtrlW.
  • Reopen the last closed space - CmdShiftTCtrlShiftT.

Only the active space listens for canvas shortcuts.

Right-click a space tab to open its project folder in Finder, Explorer, or your file manager.

Windows

Open another window with CmdShiftNCtrlShiftN. Drag a tab out of the tab bar to move that space into a window of its own, and drag it onto another window's tab bar to move it back.

Focus on one pane

Press CmdShiftEnterCtrlShiftEnter or CtrlShift2CtrlShift2 to make the focused or selected pane fill the canvas beside the sidebars. Every pane header also has a maximize button. A maximized pane shows its text at the same size as the Coordinator beside it, not zoomed up. Terminals gain columns and rows at the same font size, and the transcript, composer and footer share one centered column that fills the pane when it is narrower. Set that column's width with Expanded content width in Settings -> Appearance. The sign-in card, attachments, banners, notices, permission prompts, queued messages and the usage card above the composer follow that column. A team lead or pane the Coordinator or an agent creates while you have a pane maximized opens on the canvas without taking over the maximized view, moving focus or moving the camera. A maximized pane does not draw the selection outline; a pane that is not maximized still shows it when selected. Maximizing a terminal or agent pane, an editable note or a browser page moves keyboard focus into it, unless you were already typing there. Press the shortcut again, the button, or EscEsc to restore your exact pan, zoom, and transcript reading position. While focus is inside the pane, the first EscEsc leaves it (press it twice quickly in a terminal or agent prompt) and the next one restores. Selecting another pane while maximized fills the canvas with that pane instead, and so does stepping back or forward through focus history. Restoring then centers the pane you ended on, not the view from before you maximized.

The × on a maximized pane removes it from its tiles, or leaves the maximized view when it is the only pane; the pane stays open. Closing a maximized pane with the close shortcut takes you to another eligible pane and keeps it maximized. Closing its workspace tab keeps maximization in the destination tab when a pane there can be maximized. Recently visited panes and tabs take priority, with a nearby one as the fallback.

On macOS, Maximize pane used to be Cmd+Shift+2, which screenshot tools such as CleanShot also take. A shortcut you set yourself in Settings stays as it is. Maximize pane once zoomed to selected panes; it now maximizes one pane. To zoom to a selection without maximizing, press CmdKCtrlK, type >> to open Commands, and choose Zoom to selected panes.

Moving and arranging panes

  • Drag a pane's header to move it. While you drag or resize, edges snap into line with nearby panes.
  • With panes selected, the arrow keys nudge them. Hold ShiftShift for a bigger step.
  • Moves, drags, arranging, grouping and ungrouping can all be undone with CmdZCtrlZ and redone with CmdShiftZCtrlShiftZ.
  • New panes, including new team leads, are placed in free space instead of on top of existing panes.
  • Right-click any pane in a team and choose Select team to select its lead, the lead's workers and their workers, and the notes, terminals, browsers and other panes linked to the lead or its workers, so you can move or arrange the team together.
  • Link panes by dragging: select an agent, or a non-agent pane such as a note, terminal or browser, then drag one of the dots on its edges onto the other pane. Every link has an agent at one end. A worker can hold its own links, and only that worker can read, message and drive what it linked; it still shares its lead's links. A worker can't be linked to its own lead, which it's already joined to, and a worker running on another computer shows no dots. Drop the dot on empty canvas instead to open the spawn menu there, offering the panes that pane can link to; the one you pick is created already linked. An agent’s menu also offers Title and Insert Media; images and videos you choose are created linked to that agent. Picking an agent from the spawn menu a team lead's dot opens adds an idle worker under that lead, ready for its first message.
  • Disconnect an agent from a pane it's linked to: click the line between them (Shift-click or CmdClickCtrlClick to add more, or drag a box from empty canvas over the lines without touching a pane) and press Delete or Backspace. Lines from a lead to its own workers can't be selected. For a team lead's links, you can also right-click linked panes and choose Disconnect from followed by the lead's name. Right-clicking a line also offers Disconnect. Disconnecting a selected line, by key or by its right-click menu, shows an Undo toast. Hover a line to see which two panes it links, and double-click it to glide to the pane at the other end; double-click again to come back.

Tile panes on the canvas

Drag a pane by its header onto another pane's edge. While you drag, the half it will take is highlighted; release to tile the two panes side by side or one above the other. Drop more panes on a tile's edges to build a larger tile.

  • Drag the divider between two tiled panes to resize them.
  • Drag any member's header to move the whole tile.
  • Right-click a tiled pane and choose Tile layout to rearrange the tile: 2 columns, 2 rows, 1 + 2 stacked, 2×2 grid or 3 columns, depending on how many panes it holds. Choose Untile to take that pane out of the tile. With 2 to 4 panes selected, Tile layout tiles them in the layout you pick. A tile holds up to 4 panes.
  • Tiles, and the sizes you dragged them to, stay as they are after a restart. Tiling and untiling can be undone with CmdZCtrlZ.

To tile panes while one is maximized, see Tile a maximized view.

Large canvases

Zoom out until the canvas fits and cold terminal, worker and lead panes show as title cards: the pane frame and header, with the title first. Zoom back in and the full pane mounts again. Panes far outside the view are not drawn until you scroll near them. Connectors between leads and workers simplify into shared rails when you are zoomed out. Opening, closing or moving a pane stays responsive on a canvas with about 1,600 panes.

Workspace explorer

The left sidebar lists the panes in the current space.

  • Toggle it with Cmd\CtrlB. If you turn on Coordinator in left pane under Settings -> Agents, the explorer moves to the right edge and CmdShift\CtrlShift\ toggles it.
  • Search titles and metadata with CmdFCtrlF.
  • Select a row to center its pane on the canvas. Clicking a group row reveals the whole group.
  • Right-click a pane and choose Reveal in Explorer to open the explorer, expand the sections around that pane and select its row.
  • CmdClickCtrlClick rows to select several panes at once.
  • New profiles group teams by status; profiles you already had keep their manual order until you change it in Sort & organize. Grouped by status, teams sit under Needs your attention, Working, Idle and Done, each in the order you pick under Sort by, with empty sections hidden. A team needs your attention when it's waiting on you or its lead failed, and a failure moves it to Needs your attention. A team is Done when its lead is idle and its pull request is merged. A group takes the most urgent status among its members, and a worker's own failure doesn't move its lead's team. In a group's status dot, a member that's working outranks one whose last turn failed. Click a section header to fold it. It stays folded when you jump to a pane inside it, and Reveal in Explorer opens it. A folded header keeps its count and shows the Needs you pill when a team inside is waiting on you. Change this in the Sort & organize menu beside the search field; the choice is remembered per space. Sort by: Type lists team leads first, then other agents, terminals, browsers and everything else, most recent first within each.
  • Drag a row into or out of a group, except while grouped by worktree or account. To drag rows into your own order, choose Manual order in Sort & organize. Grouped by status, a row drags only within its own section, and a team that changes section keeps its place in your order. A group row drags as one block with everything under it. Workers are nested under the lead that started them.
  • A team lead that's only linked to another lead stays its own team, with a Linked: row. Select a name there to focus that lead.
  • Expanded rows draw a dashed guide down their children, so you can see where a group ends.
  • Pull request status for an agent's work shows on its row.
  • A local GUI team lead with a current plan shows its completed-step count and active step below its name, so you can follow progress without opening the conversation.
  • An amber Needs you pill marks a team waiting on you, on the lead's row and on any collapsed row or group that holds it. The explorer header counts them, and CmdShiftUCtrlShiftU jumps to the next one. It shows only when an agent really needs you: a lead calls request_attention for a decision only you can make, a lead in a conversation pane stops its turn on a usage limit or an error, or a permission, plan or question prompt on the lead or one of its workers is waiting. A lead that ends its turn on a question isn't flagged while the Coordinator is on, because the question goes to the Coordinator; with the Coordinator off, a lead in a conversation pane that ends its turn on a question is flagged. A question, usage-limit or error flag clears when the lead starts its next turn. Otherwise it clears when you reply in that pane, from the desktop, your phone or a voice call, or when the lead calls clear_attention; a message from the Coordinator or a worker doesn't clear it. Hover the row and select the × inside the pill to dismiss it; a waiting prompt stays until you answer it. The pill resets when AgentGrid restarts.
  • One-off runs appear in Scheduled, above the repeating Loops section. Loop rows show a ring counting down to the next run; select a row to edit it inline, or use its hover actions to run, pause or stop it.
  • Right-click the explorer and choose Collapse all or Expand all to manage a large hierarchy.
  • New teams start folded, and a team you unfold stays unfolded, even after a restart. The first time this applies in a space, its open teams fold once too; unfold any you want open. To have new teams start open, turn off Settings → Appearance → Status bar & sidebar → Auto-fold new teams.
  • Rename the selected pane with F2F2. F2 works for agent, worker, terminal, browser, note, and other renameable panes.
  • Click your name at the bottom of the explorer to open the account menu: Settings, Help & docs, What's new, Keyboard shortcuts, and Manage account and Sign out while you're signed in (Sign in otherwise).

An expanded group has a rail beside its visible members that stops before the next sibling row, including when a filter opens the group.

Folded and expanded groups are remembered per project. Activity dots identify panes and space tabs that are working or running, so background work remains visible even when another space is active.

Tile a maximized view

Drag a pane's header, its sidebar row, or a pane chip or pane card in a conversation onto a maximized pane. Drop at an edge to tile it beside or below the panes already there. Tiling works in the normal maximized view without an experimental setting. Drag the gaps between tiles to resize them.

Drag a tile off the tiled view to return it to the canvas. Undo with CmdZCtrlZ puts it back in the same spot. When nothing is maximized, drag a sidebar row anywhere onto the canvas to maximize that pane.

You can also ask a team lead or worker to maximize or tile panes, for example to put itself beside a browser, and to put the view back afterwards.

In the maximized view, a tile's × is labelled Remove from tiles when there are two or more tiles. On the last pane it is labelled Exit maximized view: it leaves the maximized view and keeps the pane open. To archive a pane, use the close shortcut.

Narrow tiles keep the pane icon and title readable. Below a 280 px tile width, less-used header buttons hide while × and the icon stay visible.

Focus history

AgentGrid remembers the panes you focus, across spaces. Step back to the pane you were just in, at the zoom you left it, without searching the minimap again:

PlatformBackForward
macOSCtrl-Ctrl-CtrlShift-CtrlShift-
Windows / LinuxAlt←Alt←Alt→Alt→

Both commands can be rebound under Settings -> Shortcuts.

For quicker jumps, open the Omnibox with CmdPCtrlP or CmdKCtrlK. It searches panes in every space by name, alias, pull request or harness. Matching commands appear above weak pane matches, each with its current shortcut. Press EnterEnter to open the highlighted match; if its group is collapsed, AgentGrid unfolds it to reveal the pane. Press ShiftEnterShiftEnter to select a pane without zooming: the canvas pans to it at your current zoom. Type >> first to list only commands.

Minimap, filtering, and organization

The minimap shows the camera's position in the larger workspace. The pane counter updates as panes are added or removed. Use the filter menu beside the search field in the workspace sidebar to dim panes that do not match a type or status filter without moving them. Its Type chips include Team leads and Groups; Groups shows only group rows, with a count. The same menu opens the Archived list and your Call history. Zoom-to-selection centers the selected group, and ordinary zoom stays centered under the pointer.

While a filter is active, activity dots describe each listed pane's own work. A team lead included only to show a matching worker's parent does not count as another working pane. Group counts and dots follow the matching member rows; without a filter they summarize the whole group.

To tidy up after a large parallel run, select some panes and press CmdShiftRCtrlShiftR, or choose Reorganize group from a group's menu. Leads go top-left with their workers wrapped beneath.

Appearance

Choose a theme under Settings -> Appearance. Until you pick one, System follows your computer's light or dark appearance as it changes (Linux stays dark). Light mode uses a dedicated terminal ANSI palette for readable output on light surfaces, and your theme persists across restarts. Buttons, menus, chips, focus rings and hover states use the same neutral style as Settings in every theme; only the selected pane's outline uses the theme accent.

The same page has:

  • Connector style - Tracks (the default) animates the lines between leads and workers; Classic draws plain lines.
  • Application scale - makes the whole interface larger or smaller without changing canvas or pane zoom.
  • Status colors - pick your own colors for Working, Unread, and Terminal activity.
  • Highlight color - recolors focus rings, counters, the Send button, primary buttons and other solid highlights such as the read-aloud word, slider thumbs and split dividers. T keeps the theme default. Text on those fills switches to black or white, whichever reads better; in the light theme, highlighted text and focus rings use a darker mix of your pick so they stay readable.
  • Expanded content width - the width, from 600 to 1200 px, of the centered conversation column in a maximized pane or the maximized Coordinator.
  • Show PR numbers and Show PR status independently control PR numbers and status icons, colors and labels. Turn both off to remove PR badges; ordinary branch text, running/unread dots and descriptive link text and navigation stay available.

A typical navigation loop

  1. Open a space and bind a project folder.
  2. Spawn an agent with CmdNCtrlN.
  3. Hold OptionCtrl and drag to move the camera.
  4. Use the explorer to jump to a specific worker.
  5. Run Zoom to selected panes from the command palette to bring the selected panes back into view.

For pane types and spawn behavior, see Panes. For every binding, see Keyboard shortcuts.

On this page

Ask AI

Ask a question about AgentGrid. Answers come from these docs, with links to the pages they use.

AI answers can be wrong. Check the linked pages.