AgentGridAgentGrid Docs
Core Concepts

Panes

The pane types AgentGrid places on the canvas and how to spawn, rename, move, and restore them.

A pane is a movable unit on the canvas. Every agent, terminal, browser, note, title, source-control view, simulator, image, and video is a pane with its own position, size, and state.

Pane catalog

ShortcutPaneWhat it opens
Cmd1Ctrl1 through Cmd3Ctrl3AgentsThe first three installed and enabled harnesses, in the order shown under Settings -> Agents. A project's Default agent comes first, and agents the project blocks are left out.
Cmd4Ctrl4TerminalA PTY-backed shell in the space's project folder. Right-click to read the visible screen or selected text aloud (Pro).
Agent pane actionSource ControlReview the agent's worktrees, diffs, commits, and pull requests.
Cmd7Ctrl7BrowserA Chromium browser pane with DevTools. Right-click a page to copy text or links, or to copy or save an image, or choose Read aloud to hear the page's main text, or Read selection aloud for selected text (Pro).
Cmd8Ctrl8NoteA markdown note with editing and dictation. Reading a note shows its Markdown tables as tables.
Cmd9Ctrl9TitleA section heading for visually grouping panes.
CmdShiftMCtrlShiftMInsert Media...A picker that creates an image or video pane.
Spawn menu, under WorkspaceSimulatorExperimental and off by default: turn on Settings → Advanced → Simulator panes (experimental) to add one. Lists the simulators and emulators on this machine (iOS simulators on a Mac, Android emulators where the Android SDK is installed) and saves the one you choose for the project. While the switch is off, a Simulator pane you already have shows where to turn it on and keeps its saved device.

Additional enabled harnesses live under Other agents in the spawn menu. The menu always shows the current positional shortcut next to the harness it will open.

Insert Media is an action, not a stored pane type. The selected file becomes either an image pane or a video pane.

Workers are created by masters rather than the spawn menu. A worker pane records its harness, role, selected model, working directory, status, and transcript.

Each project's browser panes keep their own cookies and sign-ins. Browser panes opened without a project folder share a separate set, and their pages can't request files from your computer. Refreshing a browser pane reloads its page. When an agent refreshes it for you, the rest of the workspace stays in place.

Simulator panes on Mac

Turn on Settings → Advanced → Simulator panes (experimental), then choose Simulator from the spawn menu and select an installed iOS device. Xcode and its simulator runtime are required. Booting waits for a shared machine slot; once connected, tap or drag the screen in the pane. Video fits the pane, follows device orientation and reconnects after a dropped stream.

A simulator session survives moving its space to another window. Closing the pane or quitting AgentGrid stops its helper and shuts down a device only if that pane booted it. An already-running device is left running. The experimental switch is off by default. Android and non-Mac hosts can show device selection, but do not provide this live iOS screen.

How panes appear

  • Press CmdNCtrlN or right-click empty canvas to use the spawn menu. While a pane is maximized, CmdNCtrlN opens a new agent instead, with the project's Default agent if it has one, or else your last-used harness.
  • Use Cmd1Ctrl1 through Cmd9Ctrl9 for direct positional shortcuts.
  • Open Source Control using the Source Control button on a team lead or worker pane, including agents running in the background service.
  • Drop an image or video on the canvas to create a media pane.
  • Drop PDFs on empty canvas to open each one in its own pane, titled with the filename.
  • Drop an image on the Coordinator or a docked conversation, including over its history, to attach it there. The conversation highlights while the file is over it.
  • Choose Add pane from an agent’s Explorer row or pane menu to create a linked pane. Title and Insert Media are available there too; selected images and videos are linked automatically.
  • Let a master call spawn_worker or spawn_role to add a worker.

Dropping a folder sets the space's project folder; it does not create a pane.

Select, move, and rename

  • Click a pane or its header to select it. Clicking or tabbing into an agent's composer also selects that pane.
  • Use CmdClickCtrlClick to add or remove panes from a multi-selection.
  • Drag a pane's header to move it. Every selected pane moves together.
  • With panes selected, the arrow keys nudge them; hold ShiftShift for a bigger step.
  • Press F2F2 to rename the selected pane. This works across agent, worker, terminal, browser, note, and other renameable panes.
  • Double-click a pane header to rename it in place.
  • Press EscEsc to clear selection.

On your connected phone, long-press a pane on the canvas to grab it, drag it, then release to place it. The new position also appears on your desktop canvas.

The context menu displays the current rename shortcut if you rebind it.

Agent masters receive an automatic title from the first substantive prompt and response. A manual rename takes precedence, so AgentGrid will not overwrite the name you chose.

Unread replies and return to latest

While you are scrolled up in a desktop conversation, the down-arrow Scroll to latest button above the composer counts new replies and team-lead status messages. This works in the Coordinator, team leads and workers. Select it to return to the newest message. Reaching the bottom clears the count; it also clears if resizing or folding content brings all messages into view. Streaming chunks, tool activity and thinking do not add extra replies to the count.

The button floats over the conversation without reserving a blank strip above the composer.

By default, an ordinary message you send brings you to the bottom. Turn off Jump to my message when I send under Settings → Agents to keep your reading position. Quote replies keep your place. Click a quote you send with Quote Reply to jump to the original message (quotes of tool output or thinking can't jump), in this pane or another one; it scrolls there and briefly highlights the passage. If the original is gone, AgentGrid says so. Messages sent into an already-running turn keep their existing scroll behavior.

Find in pane

Use Find in pane to search a conversation. Closing search keeps the line you were reading at the same position, including in the Coordinator and maximized panes. If you close it at the bottom, the conversation keeps following new replies.

Groups

Select two or more panes and press CmdGCtrlG to wrap them in a named group. CmdShiftGCtrlShiftG, or Ungroup in the menus, takes the selected panes back out; a group left with fewer than two members dissolves.

  • Drag a group by its header to move everything inside it.
  • Double-click the group name to rename it. The Group menu also sets its icon and colour.
  • Hide contents folds the group into a compact card; double-click the card to show it again.
  • Reorganize group, or CmdShiftRCtrlShiftR on a selection, lays the panes out as a tidy team: leads top-left, workers wrapped beneath.

Duplicate and fork

Right-click a single pane and choose Duplicate or Fork when the action is available.

  • Duplicate creates an independent copy of a terminal, browser, note, title, image, or video pane with the relevant visible state. A duplicated terminal starts a fresh shell rather than replaying the old process.
  • Fork on an agent whose harness supports it creates a new pane branched from the source conversation. The original session remains unchanged.
  • Source-control panes cannot be duplicated because a space owns at most one.

Right-click an agent or terminal pane on this computer and choose Open in VS Code to open that pane's folder in your own installed VS Code, with your profile, extensions and GitHub sign-in. AgentGrid shows an error if VS Code isn't installed.

Copies appear offset from the source and AgentGrid searches for nearby free space instead of stacking panes directly on top of one another.

Close, archive, and restore

You can also close a pane by right-clicking its row in the workspace explorer and choosing Close, which does the same thing.

On Mac, CmdShiftBackspaceDelete closes the focused or selected pane, even while typing in a composer, terminal or browser page. On Windows and Linux, Delete closes selected panes when canvas has focus. Backspace, including Mac's fn+Backspace forward-delete key, no longer closes panes by default on Mac.

The header X normally closes a pane. In the maximized view it is labelled Remove from tiles when there are two or more tiles, or Exit maximized view on the last pane, which stays open; see tiling. A DevTools pane that closes itself still closes, including while maximized.

The closed pane is archived, and a toast offers Undo. The exception is an agent pane that never started a session, or a blank note with no file yet, which is simply removed because there is nothing to keep. A team lead or worker with a session is archived, even when the project has no archive folder yet. If AgentGrid can't archive it, the pane stays open and says why. Undo with CmdZCtrlZ and redo with CmdShiftZCtrlShiftZ. Restoring a resumable agent pane keeps its session, and restoring a master brings back its workers in the same step.

The Coordinator waits for archiving to finish before reporting which panes it closed.

When an agent connected to AgentGrid's MCP server closes a pane, the panes under it close too and go to the same history, so one Undo brings them all back.

Pending terminal cleanup on Windows no longer prevents archiving a pane; AgentGrid finishes the cleanup in the background.

Closing a whole space asks first only when agents are working or terminals are running in it.

Open Archived from the filter menu in the workspace explorer to find older panes. The list is searchable, grouped by Today, Yesterday, Previous 7 days, and Earlier, and shows whether you or an agent archived each item. Each row has Restore and Delete permanently.

Workers that an agent closes are archived like any other pane and can be restored from Archived.

AgentGrid also attempts to recover agent panes after a CLI crash, out-of-memory exit, renderer crash, or app restart. Resumable sessions reconnect to their recorded session id; if automatic recovery is not possible, the pane keeps the failure visible so you can retry or restore the session deliberately. If the window itself keeps crashing, AgentGrid offers Reload window and Quit.

Stop, close and what keeps running

  • Stop ends the agent's current turn. The pane, its conversation and the workers, terminals and browsers it started keep running; a command it was running may be cancelled.
  • Close archives the pane and ends its processes. Closing a lead also closes the workers, terminals and browsers it started, including dev servers running in those terminals. On Windows, AgentGrid ends each terminal's whole process tree.
  • Worktrees stay on disk. Closing or archiving a pane never deletes a git worktree or its branch. When a pull request AgentGrid tracks merges or closes, it removes that pull request's worktree under .agent-grid/worktrees/, keeping the branch, but only when nothing can be lost: no uncommitted changes or untracked files, no unpushed commits, no open pane or running program inside it, and no local-only files such as a changed .env.local. Otherwise the worktree stays until you delete it, and the team lead that owns it is told why. Common build output, such as .expo/ and next-env.d.ts, doesn't count as local-only. To let cleanup also remove other files your repository regenerates, commit a .agent-grid-prune-safe file at the repository root on its default branch, listing one path per line; a trailing / covers a folder and everything in it. AgentGrid reads the list from the default branch, and a listed path counts only while git ignores it: tracked, modified and untracked files are always kept. If a lead's worktree folder disappears while AgentGrid runs, however it was removed, the lead is told and pointed to any archived copy under ~/.agent-grid/archives/worktrees.

Next

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.