Agents and workers
How team leads coordinate workers across installed AI harnesses and models.
AgentGrid distinguishes a team lead from the workers it starts. A team lead plans and coordinates; each worker handles a bounded task in its own visible pane. Above your team leads, the optional Coordinator keeps track of them all from a sidebar.
Team lead and worker
- A team lead is a harness pane with AgentGrid's orchestration tools enabled. There is no separate team lead pane type: a compatible agent pane becomes a team lead when it starts or associates another pane.
- A worker is an agent the team lead starts with
spawn_worker,spawn_role, orresume_worker. Workers can run on any installed harness, with an optional model selected for that task.
When harness is omitted, a worker inherits the team lead's harness. This makes a same-provider team the shortest path while still allowing mixed teams such as a Claude builder, Codex reviewer, and OpenCode validator. Workers also inherit the team lead's effort unless the team lead picks one for that task. GPT-6 Sol models are the exception: when nobody chose an effort, they run at medium, even under a higher-effort lead. A saved default in Settings → Agents still wins.
Workers get the MCP servers you've added to your own harness setup, such as Linear or Azure DevOps, the same as team leads. AgentGrid's own connection stays scoped to each worker's role. Pi doesn't support MCP servers.
Claude workers using the terminal backend also get AgentGrid's canvas tools and, when their role and access level allow it, terminal tools. Your own MCP servers stay available. A read-only worker gets canvas tools without terminal tools.
Every worker appears on the canvas with its harness, role, activity, working-directory badge, a live elapsed timer, and its transcript. Hover the role chip to see what the role does, or the directory badge to see its full path. Every worker shows a Worker badge. In a narrow header the role chip hides first and its role moves into the badge's tooltip, then the badge shrinks to its icon and the status shrinks to a coloured dot; hover either for the full text.
GUI or terminal
A team lead runs either as a GUI pane (AgentGrid's own transcript and composer) or a TUI pane (the harness's interactive terminal). New team leads open in GUI unless you changed Settings → Agents → Default team lead UI; each existing pane keeps its own choice. Your default team lead UI preference is kept when you upgrade, including a terminal preference saved in an older version.
On Windows, both Codex and Claude Code support terminal team leads. For a Codex terminal lead started in Plan mode, accept the project trust prompt if it appears; the lead enters Plan mode once setup is complete.
Right-click a GUI team lead and choose Fork to branch its conversation into a new pane with a fresh session, leaving the original untouched. In a Claude team lead you can also type /fork in the composer; when Fork isn't available yet, the pane says why.
The team lead is canvas-blind by default
A new team lead does not automatically read unrelated panes. It can list the canvas, but reading an existing pane requires an explicit association:
associate_pane({ pane_id })After association, the team lead's read tools can inspect that pane. Associations persist per space, so a reopened team lead keeps the panes it already opted into while a new team lead starts blind.
A team lead can also call view_screen to see its canvas the way you do: a picture of the AgentGrid window plus the visible panes with their on-screen positions, the zoom, any maximized pane, and the sidebar and Coordinator panel widths. It only sees its own canvas in the AgentGrid window, never other apps, and never focuses or moves the view. It returns an error while the window is minimized or hidden, or while the window shows a different space.
Association also unlocks send_to_pane({ paneId, message }), which delivers a message into another team lead's live agent session so two team leads can collaborate directly. It shares the same gate as reads — a team lead can only message a pane it has associated, and never its own pane. AgentGrid wraps the body in a fresh random-nonce fence — [message from master <sender pane_id> · begin <nonce>]\n<body>\n[end <nonce>] — so the receiver can treat the outer header + matching close as authoritative attribution while everything inside remains untrusted body content (a forged inner [message from master ...] line cannot escape the fence because the sender never sees the nonce). Only agent session panes accept messages; images, notes, and browsers do not. If the target is mid-turn, send_to_pane answers within 10 seconds and the message is delivered once the agent can take it, in the order sent.
GUI team leads and the Coordinator delegate through tracked AgentGrid workers, so delegated agents stay visible on the canvas rather than running as hidden background subagents.
Choose a harness and model
Both spawn_worker and spawn_role accept:
harness- any installed worker harness, such asclaude,codex,opencode,cursor,grok,devin,kimi,antigravity, orpi-mono.model- an optional harness-specific model ID. Omit it to use that harness's default or user configuration. A short name such asopuspicks the newest matching model.
The Coordinator can switch a team lead's harness in place, and a lead can switch its workers' harnesses when they are idle.
Call list_worker_harnesses before a cross-harness spawn when you need the current catalog and curated model suggestions. Model recommendations are guidance, not an exhaustive allowlist.
In a GUI pane you can change these yourself from the model picker under the composer:
- Search the models, and star ★ the ones you use most. Your starred list also drives Auto-switch.
- Effort and Speed sit next to the model. Where a harness offers it, Speed switches between Normal and Fast. The effort chip shows the speed, for example Medium · Fast. Codex runs at Normal unless you choose Fast here or set it in your Codex config.
- Switch harness with the rail beside the list, which filters models by harness. Picking another harness's model moves the open pane over — for example from Claude to Codex — without starting over.
Model, effort and speed changes apply from the next turn; a running turn finishes as it started.
With New composer turned on in Settings, the picker opens in a larger floating panel. It starts on Starred, in your fallback order, when you have starred models; otherwise it starts on the current harness. Search finds models across harnesses. The effort chip opens Reasoning effort, with descriptions of the available levels and a reminder that higher effort can take longer and use more tokens.
To set the model new panes start with, open Settings → Agents, choose a harness and pick its Default model. It's the same picker, limited to that harness: search it, find your starred models first, or type a model ID that isn't listed where the harness accepts one, such as OpenCode. If OpenCode doesn't know a typed model, the first turn says so and suggests the closest match.
A project can set its own default model, effort and speed on its Agents page; see Project settings.
Permission modes
Settings → Agents → Default permissions sets how much workers and terminal (TUI) team leads may do without asking. It applies to new panes; panes already open keep the mode they started with.
- Default — Claude asks before writing files or running commands (Codex runs without asking, so it can work as part of a team). Each request shows Deny, Allow for session (don't ask again for exactly this, this session) and Allow once.
- Auto — Claude uses its own safety classifier for routine commands. Calls it cannot approve can still ask you. When Claude supplies a suitable project rule, Always allow saves that rule in the project’s
.claude/settings.local.json; Allow for session stays session-only. - Plan — agents write a plan and wait for your approval before making changes.
- Bypass Permissions — no checks at all. Meant for CI and automated environments.
When a worker stops to ask for permission while AgentGrid is in the background, a desktop notification tells you, if your system allows AgentGrid notifications; click it to open the worker's pane. The lead that started the worker also sees that it is waiting on you.
GUI team leads start with the most permissive mode their harness supports unless you choose a per-pane access level.
Access levels in composers
Turn on Settings → Agents → Show per-pane permissions to choose an access level in GUI team lead, worker and Coordinator composers. The selector is off by default. Leaving it off preserves existing pane behavior; hiding it again does not clear a level you already chose.
- Read-only — available for Claude and Codex workers only; the worker cannot change files itself. Team leads and the Coordinator do not offer this level.
- Supervised — ask before commands and file changes.
- Auto-accept edits — approve edits automatically, ask before other actions.
- Auto-approve — supported providers approve routine actions; others still ask.
- Full access — allow commands and edits without prompts.
Unavailable levels are disabled with an explanation for the selected harness. Changes apply from the next turn. A worker runs at its own level from its first turn. A worker with no level of its own runs at its team lead's level, but only when that gives it no more access than it would otherwise have, so a Supervised team lead's workers run Supervised too. Claude and Codex GUI leads can show approval requests in their pane and on your connected phone.
A worker's chip shows the level it actually runs, including an inherited level, rather than an unsupported saved choice. When space is tight it folds to a shield; hover to read the level. Agents may change access only down their team tree: the Coordinator can configure its leads, and leads can configure their workers. They cannot change their own access.
Plans from every major harness show as a plan card. When folded, a plan shows the current action when the agent supplies one. Local GUI team leads can also show completed tasks and the current step in the Explorer; the summary waits for a complete live plan and can be absent after reopening.
Slash commands
Type / in a GUI composer to see what's available. Besides each harness's own commands, AgentGrid adds:
| Command | What it does |
|---|---|
/loop [5m] <prompt> | Rerun a prompt in this pane on an interval, or let the agent pace it. The pane's loop chip shows the current run, such as Run 3 or Run 3 of 20, and its tooltip shows when the next run starts. A team lead in a conversation pane that's running review rounds shows them on the same chip, such as Review round 3 of 4. |
/schedule <when> <prompt> | Run a prompt later (in 20m, 3pm, tomorrow 9am, every 2h, or a cron). |
/goal <condition> | Keep going after every turn until a condition is met. A goal or loop with a run limit ends with a notice when it reaches the limit. |
/resume | Reopen a past session in this pane. |
!<command> | Run a shell command in the pane's folder without starting an agent turn. It shows as a Bash row, and its command and output go to the agent with your next message. Only a ! as the very first character counts, so start with a space to send ! as text. Desktop composer only; from the phone, ! is sent as text. Shell mode is off for Read-only workers and for panes running on another computer. |
/login, /logout | Sign in, switch this agent to another account, or sign it out on this computer. |
/rc | Turn on Claude's Remote Control in a Claude team lead (see Coordinator). |
/ship, /ticket, /worktree, /pr, /review-pr | Built-in skills for taking a change from issue to merged pull request, available in every project. |
The list also includes your own skills (.claude/skills/<name>/SKILL.md) and, in Claude panes, your Markdown commands (.claude/commands), from the project folder and your home folder. In a Claude pane, ones from your home folder appear as /agentgrid-personal:<name>. A pane running on a remote host lists that host's skills and commands.
Add clear to /loop, /schedule or /goal to stop it. Repeating runs appear in the Explorer's Loops section; one-off runs appear in Scheduled. Click a normal loop to edit it, or use Run now, Pause/Resume and Stop; goals allow prompt/run-limit edits. Scheduled rows offer editing, Send now, Snooze and Delete, or Release when held. The built-in reflection row opens its owner. Run now is unavailable for paused, due or in-flight loops. A loop waits while its account is out of usage, and starting the same loop twice reuses the one that's running.
The shared When editor offers one-off, interval and calendar-based timing. Choose the date and time from its popover or type the time directly. For a repeating loop, Let the agent reschedule or stop it lets the agent choose the delay after a completed turn without replacing your saved cadence. The next run waits for that turn to end. If it gives no new delay, the saved cadence is used; missed calendar slots are skipped. An interrupted run pauses the loop, and a restart during a run brings it back paused. Resume it to run again.
New loop, schedule and goal prompts appear as compact rows in desktop conversations. The row names the kind of run and shows the first line; expand it to read the full prompt. Your own messages keep their normal bubbles. Scheduled prompts keep their compact rows after a restart or conversation reload.
Send feedback to the AgentGrid team
When an agent runs into a problem in AgentGrid itself, it can send a bug report to the AgentGrid team, and it can offer to send your feedback when you want AgentGrid to work differently. AgentGrid removes secrets, tokens and email addresses it recognizes, and replaces your home folder with ~. While Share usage data is on, which is the default, bug reports and any other feedback an agent sends go straight away, without asking you. While it's off, AgentGrid shows you exactly what would be sent, and nothing goes until you choose Send; Don't send discards it. You need to be signed in.
Worker sessions and resume
Workers are long-lived. Reuse an existing worker with send_to_worker when the follow-up belongs to the same role and context. This preserves its full conversation and avoids duplicating panes.
If a Claude worker is busy, for example in a long tool call or waiting on a permission prompt, send_to_worker answers within 15 seconds that the message is queued, so the lead can carry on. The message isn't cancelled: the worker reads it at its next step. A message you type into the worker pane yourself still waits until the worker reads it. A follow-up to a busy Grok, Cursor, Kimi, Devin, Pi, Hermes or Antigravity worker waits for its turn to end and runs as its next turn; only Stop or interrupt_worker cuts a worker's turn short. When a worker running inside the app, rather than in the background service, stops on a permission prompt, its lead gets a notice, so an unattended team doesn't stall in silence. When the worker finishes the work a lead sent, the lead hears about it, even if the message went into a turn the worker had started on its own, such as waking for a background job. If a worker's turn ends while background jobs it started are still running, those jobs stop and the lead hears how many.
After an update or restart, GUI team leads and workers show their saved conversation while the session reconnects. A message sent to a lead from the Coordinator or your phone waits for its saved session to restore before delivery.
If the underlying session is gone, the saved history stays visible and the pane shows Session not found on a team lead or Session ended on a worker. Choose Resume to pick a saved session, or Start new for a fresh conversation.
After a restart or team lead resume, use list_my_team to rediscover visible workers. Use list_recoverable_sessions to find recoverable sessions across installed harnesses, then pass the returned sessionId and harness to resume_worker.
Claude's interactive team lead sessions also appear under Sessions -> Resume Claude in the spawn menu, scoped to the active project folder.
Streaming and control
Worker panes stream text, reasoning, and tool activity as the turn runs. A team lead can read output, wait for one worker or the first of several workers, send a follow-up, and stop a worker. If a worker is interrupted, the transcript keeps the output already rendered.
When a background job wakes a worker, its lead is notified after the worker finishes handling that wake-up. The lead can then continue the task without waiting for a manual check.
After three consecutive empty turns, AgentGrid stops starting automatic turns for that worker and tells its lead once. Pending background notices stay queued. You or the lead can still send an explicit message; a successful turn clears the streak and lets automatic work resume. Restarting AgentGrid also clears the count.
An agent waiting on CI can call notify_when_ci_finishes({ pr }) (or { sha }) and end its turn instead of watching the run. When every GitHub check run on that commit finishes, AgentGrid wakes the agent with a new turn that reports the conclusion, each failed job and the run links. Commit statuses aren't watched. AgentGrid checks GitHub once a minute, the watch survives the turn ending and an app restart, and the agent is told if no check run starts within 20 minutes or if CI is still running after 6 hours. A watch covers one commit, so the agent asks again after a new push.
An agent waiting for a PR to be merged, reviewed or pushed to can call notify_when_pr_changes({ pr, on }) and end its turn instead of polling GitHub in a loop. on lists the changes to wait for: merged, closed, review (a new PR review, or a comment with a ✅ Ship it, ❌ or Verdict line), push, comment and ready; it defaults to merged and closed. When the first of them happens, AgentGrid wakes the agent with a new turn that says who merged or closed it, the review or comment's author, headline (its verdict line if it has one, else its first line) and link, or the old and new commit. A PR that's already merged or closed when the agent asks wakes it within a minute, if that change was requested. AgentGrid checks GitHub once a minute with one request per repository for every watched PR, the watch survives the turn ending and an app restart, and the agent is told if nothing happened within 24 hours.
For a long local job, such as a full test suite or a build, an agent can call spawn_terminal({ command, notifyOnExit: true }) and end its turn instead of waiting or polling. When the command exits or is stopped, AgentGrid wakes the agent with a new turn that reports completed or stopped, the exit code and the path of the saved output. Like CI watches, it survives the turn ending and an app restart. If the job's terminal goes away without reporting a result, for example because it never started, the agent is woken with a notice that the job was lost.
An agent can read the output of terminals it started, terminals its workers (and their workers) started, and terminals linked to it or its lead with associate_pane, through read_terminal_output and wait_for_terminal_pattern. Only the agent that started a terminal can type into it or kill it. A terminal outside those limits is refused with a message naming the agent that owns it.
A Claude agent's spawn_terminal refuses a command that matches a Bash(...) deny rule in your Claude settings, as its Bash tool does; other harnesses have no Bash deny rules, so their terminal commands run as before.
In the agent's transcript, each of these wake-ups shows as a compact row, such as CI finished · success with the commit, instead of a raw message. A failed or cancelled run is shown in red with the failed jobs. Expand the row to read the full notice and open the run links.
Claude workers, GUI team leads and the Coordinator end their process when a turn ends, so AgentGrid turns off their background commands. A command that runs past its timeout is stopped with an error instead of moved to the background, and the agent is told to rerun it with spawn_terminal({ command, notifyOnExit: true }). The Monitor tool is refused the same way. Their subagents run in the foreground too. A message you send while one of their commands or subagents is running waits until that finishes.
Agents can put a test suite or build in a machine-wide queue with agentgrid heavy -- <command>. The command waits for a free slot, shows its place in the queue and how long it has waited, then runs, so several agents don't slow your computer to a crawl. On macOS and Linux it runs below normal priority; on Windows it keeps normal priority, so a busy machine can't stall it. On Windows, its errors show in PowerShell terminal panes, and when Node 24 or later is on your PATH, Ctrl+C lets the command shut down and frees its slot. agentgrid heavy status shows who holds the slots and who is waiting. A command never waits more than 30 minutes (AGENT_GRID_HEAVY_MAX_WAIT_MINUTES changes this), a holder whose process has died or whose lock is dated in the future is ignored, and if the queue itself fails the command runs anyway after one warning. AgentGrid adds agentgrid to the end of each agent's PATH, so your own agentgrid command, if you have one, still wins. On Windows, agents' PowerShell gets an agentgrid.ps1 that passes arguments through unchanged.
Click empty space in a GUI team lead or worker pane, including its transcript, to put the cursor in its composer. Your draft and cursor position are kept. Buttons, menus, pickers and text selection work as before.
You can keep typing while a Claude or Codex turn runs: Send stays available, and your message is queued and delivered as soon as the agent can read it. An interrupted turn collapses to a compact row with Continue; a failed turn offers Retry now to resend it once. The retry button stays disabled while that retry is in flight.
When you interrupt Claude, the conversation shows a muted Interrupted system line, naming the tool when available. Failed turns keep their specific failure label.
When a turn on any harness stops at a usage limit with a known reset time and Auto-switch has nowhere to go, the turn offers to wait and resume when the limit resets. Tick Always do this to make that automatic, or set Auto-resume Claude sessions when usage resets on the Claude settings page; despite its name, it covers every harness. It's on by default, and the pane's scheduled messages wait until the reset too. On your connected phone, the team lead shows when it will resume; select Cancel to stop that automatic resume. This needs desktop 2.9.35 or later and a phone app with resume controls. Switching the waiting pane to another harness, model or account ends the wait, whether you switch it or an agent does, so its next turn runs straight away.
When a harness is out of usage on every account and there is no account to switch to, spawning a worker on it or sending a message to an idle worker on it is refused before anything starts. The error names the reset time and the harnesses that still have room.
You can rename any selected worker pane with f2f2, or ask the team lead to rename a pane it owns. Clear names make large review teams much easier to scan. To show an unread dot when a worker's turn ends, turn on Unread receipts for Workers in Settings → Agents.
A team lead can send you a desktop notification when it finishes a turn while AgentGrid isn't the app in front. Each team lead has a bell beside its Source Control button that turns notifications on or off for that pane; the choice is saved with the pane. Turn on Notify me in Settings → Agents to start new team leads with their bell on; leads you already have stay as they are until you turn on their bell. GUI team leads and Claude terminal team leads notify you when a turn ends, a turn that ends in an error says Stopped with an error, and workers send no turn-completion notifications. Clicking a notification brings AgentGrid to the front. Notify me follows whether your system lets AgentGrid send notifications. On macOS and Windows it reads AgentGrid's notification permission and stays off while the system blocks it. On Linux it checks that a notification service is running, but it can't see a per-app block or Do Not Disturb. Switching it on asks Allow notifications? first; on macOS, Allow then shows macOS's own alert the first time. A Notifications are on. banner confirms it. If your system is blocking AgentGrid, use the button beside the setting to open your system's notification settings and allow it. Switching Notify me off while notifications are allowed opens those settings, where you turn AgentGrid's notifications off.
Unsent composer text stays with a parked pane when it returns. When an idle worker parks, the terminals it started, such as dev servers, stop; their panes stay and show that they exited. On macOS and Linux, headless browser sessions it started with agent-browser close too, as they do when its pane closes. Each agent gets its own agent-browser session, including one started by another agent, so a worker doesn't take over its lead's browser. On macOS and Linux, agent CLIs and everything they start run below normal priority, so AgentGrid and your own work get the CPU first; on Windows they keep normal priority, because below-normal work can stall while other programs keep every core busy. Automatic messages to a terminal team lead leave text you are typing in its prompt alone. Stop also cancels workers that are still starting. Transient Claude worker failures retry automatically; you can stop a pending retry. After a network failure, Claude team leads retry too, and while the network is down, retries, loops, schedules and the Coordinator's loop wait without using up an attempt or run; each runs once when the provider can be reached again, or after 6 hours at the latest. To check the network, AgentGrid follows an HTTP or HTTPS proxy and ANTHROPIC_BASE_URL from your environment and from the Claude settings.json in your home folder; project and account-specific Claude settings aren't read yet. With a SOCKS proxy, a proxy combined with a NO_PROXY rule or a cloud provider such as Bedrock or Vertex, AgentGrid skips the network check and runs without waiting. A team lead's pending retry survives an app restart, and Stop on the lead cancels it.
Idle, unfocused panes keep only recent turns in the window's memory. Focus a pane or open Find to load its earlier conversation. If you are reading older messages, that history stays available until you return to the newest turn, so moving focus does not lose your place.
If full history is waiting behind other panes, a pane can show its saved transcript tail first and load the rest in the background.
Set Settings → Agents → Keep idle workers warm for to choose how long an idle Claude worker running on the Agent SDK keeps its command-line session ready for a quick follow-up: 30 seconds to 10 minutes, with 90 seconds as the default.
While an idle agent starts its command-line session, its activity reads Restarting from idle. It changes to Working when that session is ready.
Keep the computer awake
In Settings → Agents, Keep computer awake while agents work is on by default. AgentGrid also holds it while an active loop or schedule, or a PR or CI wake watch, is waiting to run, and releases it once nothing is running or scheduled; paused loops don't count. Keep awake on battery too is off by default and appears while the main setting is on. The display can still turn off or lock, and closing a laptop lid can still put it to sleep. Windows Modern Standby may still sleep; Linux needs a desktop session that honors the sleep inhibitor. Active terminal processes count on Mac/Linux, but Windows terminals do not.
Read replies aloud
Right-click a message you sent and choose Read aloud to hear it too. In a terminal, right-click and choose Read aloud for the visible screen or Read selection aloud for selected text. These actions require Pro. Shell prompts and their output may be read as one paragraph, without pauses between them.
In a browser pane, right-click and choose Read aloud to hear the page with sentence highlighting and an underline on the current word. Read selection aloud plays selected text without page highlighting. Opening another page or reloading stops playback. If a page changes while playback is paused, a highlight may remain until playback resumes.
A desktop reply with text has a play button beside its trace icon, including while the agent is still working. Read Aloud follows new text as the reply streams, and its player stays reachable while you scroll. Read Aloud is included with AgentGrid Pro and the free trial: select the button to listen to that reply, or right-click the reply and choose Read aloud. On Free, both open the upgrade prompt. To hear only part of it, select the text and choose Read selection aloud. The compact player row has labelled Pause or Resume and Stop controls, and a speed button that cycles 1×, 1.25×, 1.5× and 2×. Choose the voice and any speaking speed from 0.75× to 2× in Settings → Read aloud; both are remembered. Changing speed may repeat a short passage. Drag its track to another point. The spoken sentence and word are highlighted; click a word to jump to it. Closing the pane stops playback. Tool activity, thinking, hashes, long IDs and diff statistics are skipped. URLs are read as their site name, and long paths as their filename. Notes have the same play button in their header. Read Aloud has a daily and a monthly listening budget, which reset at the start of each local day and month. When you reach one, the reply says which limit and when it resets, and offers Get more listening. Settings → Read aloud shows today's and this month's usage. If playback is unavailable, the reply explains whether read aloud is temporarily unavailable or you need to sign in to AgentGrid.
Attachments and chips
Drop or paste images, PDFs and videos into a GUI composer. Each attachment shows a thumbnail you can remove; CmdZCtrlZ brings a removed one back. A video, PDF or image too big to send inline, or one the chosen agent can't take inline, goes to an agent on this computer as a file path instead of stopping the send. A pasted file up to 200 MB is first saved under the project's .agent-grid/attachments/; save a larger one to disk and attach it from there. Images that fit stay inline. An agent on another computer still can't take a file too big to send inline. If the chosen model can't see images, the composer warns you before you send. Images returned by tools appear inline in the transcript, and Mermaid diagrams render as diagrams.
A sent PDF shows a preview in the conversation. Select it to open the PDF on the canvas on the computer hosting that conversation.
When a turn finishes, the HTML reports, images and videos an agent made show as compact rows in its transcript. An HTML report previews right there and expands to read at full size. A video on this computer has a Play button on its row that plays it muted, right in the conversation.
Your own messages show as Markdown, like replies: headings, bold, lists and code blocks are formatted. Every code block in a conversation has a Copy code button in its top-right corner. It copies the whole block exactly, including any part scrolled out of view.
Right-click a conversation image, including in its enlarged view, to Copy image or show the file in Finder or your file manager. Showing the file is available for local images.
In a compatible phone app, tap a non-image file in the composer to preview its local copy. With desktop 2.9.36 or later, sent files can also be fetched from your connected desktop for preview. iOS opens Quick Look with editing disabled; Android offers an open-with chooser.
A photo attached from the phone shows in the transcript as a thumbnail, not a line of file details. Cursor composers accept images too: the image shows as an attachment chip and the agent sees it.
In a compatible phone app, supported attachments wait in the send queue while your computer is offline or catching up. Keep the selected computer: the queue retains the original files until delivery, and failed sends offer Retry or Discard. Queued photos show previews, and file-only messages show their filenames. A photo that cannot be displayed appears by filename instead. Video still needs a supported model on that computer.
Screenshots attached from the phone keep their original PNG when they fit the 5 MB attachment limit. Larger images still use compression. Desktop image previews on the phone load at higher detail, and opening a preview reuses the same download.
Type @ to mention another pane. Mentions, pull requests and issues appear as chips; a chip for a closed pane shows its name and offers Reopen from the archive. A pull request written as a bare link shows the same chip, labelled with its number. A lone #1 to #9, or a number that starts a list item, stays plain text.
GitHub issue and pull request links in a message appear as chips and keep the text they were written with. Select a chip to preview that pull request or issue in AgentGrid, in any repository. Links to a specific comment, file or commit, and to other sites, open in your browser.
Pull request previews show status in their header and review verdict cards ordered newest first. The Files changed tab lists the changed files as a tree, with each file's diff.
Screenshots in team-lead and Coordinator conversations use compact previews that keep the whole image visible. Click one to open the original, then press Escape to return to the conversation.
Usage indicator
The title bar shows usage for installed harnesses that expose usage data and connected API providers. AgentGrid only polls harness CLIs it detects, and the popover shows provider-specific windows, reset times, and stale or error states. When a reading can't be refreshed, the last one stays visible with its age. Used-up windows say so, for example Weekly limit reached. Usage from your other connected computers appears there too. Use Settings -> Agents to change harness order or accent colors.
For providers with separate model pools, a collapsed usage pill shows the most constrained pool that is still usable. A dot and tooltip identify exhausted pools. For example, Antigravity can still show usable Gemini capacity after its Claude pool runs out. Shared subscription limits still apply, and when all model pools are exhausted the pill shows red 100%. The percentage is usage, not the amount remaining.
For Claude, Settings and the usage popover use the same sign-in state. Usage unavailable means the usage reading could not be fetched; it does not by itself mean you have signed out.
The indicator is informational and never blocks a turn.
In Settings → Agents → Antigravity → Accounts, add another account through Google sign-in, choose a signed-in account as the default, or sign out of Main. If Antigravity stays signed in, run agy in a terminal and type /logout to finish signing out.
A harness with more than one account shows one usage section per account, and a worker or team lead can run as any of them. In a local Claude or Codex worker or team-lead pane, Run as lets you choose the next turn's account while a turn is running. The current turn keeps its account; choose that account again to cancel the pending change. The Coordinator's Run as stays locked until its turn finishes. A Codex worker that is stopped or moved to another account stays busy until its old Codex process exits; if that process is still running after 5 seconds, the switch or next message fails with an error rather than starting a second Codex session. More than one account per harness needs AgentGrid Pro. See Multiple accounts per harness.
View usage history in the popover opens Usage history, an AgentGrid Pro feature that's included in the free trial. On the Free plan, the link shows a Pro bolt and opens an upgrade prompt, unless Compute usage report (beta) is on, in which case it opens the Resources report directly; costs on pull requests remain available. Usage history charts your limits over time, links to Plan capacity, and includes Usage AI, a chat that answers questions about your usage (it needs the Coordinator turned on).
Usage history charts the full stored range you pick: 24H, Week, 30D or 90D. Shorter ranges use hourly buckets and longer ones daily buckets, with day boundaries in your local time zone. Switching ranges or closing the window stops the earlier load. For now, Usage AI, plan-capacity editing and the pull-request cost table in Usage history are unavailable, and capacity estimates use plan defaults rather than your saved override or learned values. Cost comments on pull requests are unaffected. Forward projections are available: for the part of a range after now, such as the rest of the current week in the Week range, limit lanes can show a forecast and the Overall capacity row draws a dotted one.
The Inference tab's Time per turn table splits agents' time into inference, tool wait and idle, totalled by harness, role or agent with a per-turn figure, for the range you pick. A harness that doesn't report per-call times shows unknown rather than zero.
Usage history also projects your recent usage forward: each limit can show when it is expected to hit, and overall capacity can show when it may run out or last past a reset. These are estimates based on recent usage, not guarantees.
Turn on Compute usage report (beta) in Settings to chart this computer's CPU and memory over 24H, Week, 30D or 90D. It doesn't need Pro. When Usage history is also available, an Inference | Resources switch moves between the two reports; otherwise View usage history opens Resources on its own. Resources isn't available on Windows yet, so there View usage history always opens the usage report, or the Pro explanation on Free.
Turn on Show CPU and RAM in the usage bar in Settings → Appearance → Status bar & sidebar to see recent CPU and memory beside harness usage. On Windows it shows this computer's CPU and memory only.
Resources also records temperature and battery drain when this computer exposes those readings, plus thermal pressure on Mac. Missing sensors stay unavailable rather than showing zero.
When local heavy-job queues or a remote runner are configured, Usage history includes a Factory tab. Pick 24H, Week or 30D to set the range for its history, waiting and cost figures, with that range's headline numbers at the top. Running jobs, queues and machine load always show the current state. It shows running, waiting and recent heavy jobs, the Mac mini queue, machine load and overall token capacity. Waiting behind gates lists pull requests waiting on a test slot, local tests, review, CI, merge or you, ordered by priority and then time blocked. The Mac mini can show not set up or unreachable separately from an idle queue. Slowest tools lists the tools agents waited on longest, with calls, total, median and 95th-percentile wait, and below it the open panes most blocked on them. From a job's row you can Move to front a waiting job, Stop a job, and Force stop it if it hasn't stopped after a few seconds. A pull request waiting behind a gate has Nudge lead, which reminds its team lead. Mac mini jobs and recent jobs have no actions.
The Running now section at the top of Resources shows one row per group, with AgentGrid first and agent work below. Open a group to see its programs, and open a program to see its processes with their PID, a shortened command, CPU and memory. Programs started through pnpm show their own name, such as eslint. A program with a single process shows its PID and command on its own row, which you can reach with the keyboard. Click the CPU or Memory heading to sort by it, highest first; click again for lowest first.
The CPU chart splits into AgentGrid's estimated share, other programs and idle time. An Agents in parallel lane counts the team leads and workers running a turn at once. The Agents section shows one row per team, adding up the lead and its workers; use the chevron to see each agent in a team.
Usage history keeps one account row for the same Devin or Cursor login across plan changes. Single-account harness labels show the harness name; grouped accounts use their email. Quota names stay separate from their values.
In Limits, every account row keeps each of its limits in a fixed place while you scrub across the week. A limit with no value at that point shows "—" instead of disappearing, so nothing below it moves.
On Pro and during the trial, AgentGrid builds the history in the background from your agents' session logs, in small steps so it stays light on CPU, and pauses while every AgentGrid window is hidden. It saves hourly totals as it goes, and the heavier estimate work runs in the background so the window stays light on memory. The view doesn't show import progress for now. On the Free plan, AgentGrid reads the same logs only when you use a feature that needs them, such as cost on pull requests.
Connect OpenRouter
Open Settings → Agents → Usage tracking → OpenRouter usage → Set API key, paste your OpenRouter API key, and save. The key is encrypted with your operating system's secure storage. Use Change API key to replace or clear it. No Pi installation is needed.
A capped key shows its spending cap percentage and window, such as Daily cap. OpenRouter doesn't provide an exact reset time for this reading, so AgentGrid doesn't show a reset countdown. An uncapped key shows No limit, with this month's spend and no percentage. API sources don't use the estimated weekly allowances or manual plan-capacity options for harness subscriptions.
The balance appears when OpenRouter allows access to account credits. Regular keys may show Balance unavailable; this doesn't mean the balance is zero. Key rejected means you should check the key in Settings → Agents → Usage tracking → OpenRouter usage. Rate limits and connection failures keep the last successful reading visible while AgentGrid retries.
Readings flow into Usage history on Pro. This connection doesn't import past requests, and it leaves Pi's existing OpenRouter credits row unchanged.
Connect LiteLLM
Open Settings → Agents → Usage tracking → LiteLLM usage, enter your proxy's base URL, then choose Set API key and save a virtual key. Never use the proxy's master key. The key is encrypted with your operating system's secure storage; replacing the key or URL immediately clears the previous reading.
Use HTTPS for public hosts. HTTP is allowed for localhost, private or link-local IP addresses, and .local hosts. URLs cannot contain credentials, queries, or fragments. A trailing /v1 is removed automatically.
Your personal budget appears first, followed by the team matching your virtual key. Team-only keys show their team budget. Each budget shows its spend, the percentage used, and the reset time LiteLLM reports. Each scope without a budget shows No limit and its own spend, with no percentage.
Key rejected means the proxy refused the virtual key or doesn't expose its key information; check the key in Settings → Agents → Usage tracking → LiteLLM usage. Rate limits and connection failures keep the last successful reading visible while AgentGrid retries. After a reported reset time passes, Reset unconfirmed keeps the last reported percentage and dollars until the proxy confirms a new reading.
When a proxy denies /key/info with HTTP 401, 403 or 404, AgentGrid tries /key/spend/report, then /user/spend/report only if the key report is also denied or unavailable at those statuses. These deployment-dependent routes need permission to read the virtual key's own key or user spend. Key spend only or User spend only shows the requested month-to-date date range in UTC, without a budget, percentage or reset. Model subtotals aren't added twice. An explicit zero is valid; an empty or malformed report is unavailable. No master key or owner override is used.
Readings flow into Usage history on Pro, including the free trial. This connection records new readings; it doesn't import past daily activity.
Cost on pull requests
When agents work on a pull request, AgentGrid keeps one comment on it up to date with the cost so far: total tokens and API-priced cost, tables by role (including the Coordinator) and by harness and model, and each plan account's share of its weekly window. Costs are estimates at API list prices from models.dev, refreshed daily, not what your subscription bills. A model models.dev doesn't list shows as unpriced.
Hover a PR chip's lines changed (+N −M) to see how many are Code and how many are Tests. Hover the chip to see the same cost numbers in the app: cost and tokens, the split by role, and each account's share of its weekly window, under your own account names. Usage history's By PR / feature table lists every PR's cost for the selected time range, with Coordinator work that wasn't for one PR on its own Unattributed orchestration row.
To send traces to your own observability backend, see Observability with Langfuse.
Labs (experimental)
Labs let agents test a build in a separate local macOS machine instead of your own desktop. Turn on Show Cua Lab in Settings → Advanced, then in Settings → Cua Lab, install and turn on Cua Spaces (and Set up macOS VMs on a Mac). Agents can then borrow a lab, launch a branch or pull request build in it, drive it, and release the lab for reuse or delete it when they're done. Labs are experimental and may change. Relaunch AgentGrid after turning Lab on or installing cua, so it can schedule labs. They stay off until you turn them on: agents then get no lab instructions or tools, and use tests and background browser panes instead. Even when on, a lab is optional extra QA, so an unavailable lab never holds back a merge or deploy you asked for. On the Free plan, Settings → Cua Lab offers an upgrade or the free trial instead.
Settings → Cua Lab shows your labs, pool counts and cached image. A lab that gets stuck or a creation that was interrupted appears under Needs attention with a way to recover it.
With Cua Spaces on, start with get_lab_status. This read-only tool is registered for Coordinators, team leads and workers, even when lab execution tools are absent. It reports live disabled, cua_missing or available service status, separately from execution and capacity. disabled means Cua Spaces was turned off in Settings → Cua Lab; cua_missing means install cua there. Skip lab QA until the service is available. If execution.status is restart_required, restart the pane/MCP after enabling or installing so its execution tools register. A Coordinator reports role_limited and delegates execution to a lab-capable team lead.
Agent Grid's lab tools determine availability, capacity, ownership and lifecycle. Never infer these from VM names, processes, SSH or raw host state. If capacity.status is capacity_full (or acquisition returns capacity_full), report its reason and holders and pause that lab work. Each holder names the pane and workspace holding the lab and how long it has been held. A lab held only by a running operation, such as a build terminal, shows as busy in list_labs, and acquiring it is refused with lab_busy naming that holder. If capacity cannot be read, it reports unavailable; pause lab work until it can be read. A holder name grants no permission to stop, suspend, delete or preempt it. Status can remain available when the caller already holds an active lease or a fitting running lab can be reused, even with no free VM slots. Status reads do not expire leases on disk or change computers. get_lab_status also reports serving: the AgentGrid version, build and channel answering, and the image reference and digest the next new lab will use.
When you ask to be taken to the pane holding a lab, a lab-capable agent can call focus_lab_holder({ labId, userRequested: true }). AgentGrid switches to that pane's workspace and focuses it. Agents call it only when you ask.
Use status/list → acquire → launch → scoped native Cua → release. Keep the leaseId and spaceId from acquire_lab, and follow controlGuidance in both acquire and launch_lab_build replies (including a launch without a script). Computer control stays in native Cua MCP. Without requirements, acquire_lab leases only a lab that is already running and idle, at its current size; a new or stopped lab, or a changed size, answers capacity_full. With requirements (at least { "schemaVersion": 1 }), the request is scheduled and returns queued (retry with the same requestKey), leased or refused. Sizes on a scheduled request aren't applied yet. Each acquire re-checks the lab's guest control, and returns a retryable guest_control_unavailable instead of leasing a lab whose controls aren't ready. A lab stays out of use until a late sync, build launch, build terminal or delete has finished, and the lease owner can destroy a lab while its build terminal still runs. Pass the leased ID on every call: computer_screenshot({sandbox: spaceId}), computer_click({sandbox: spaceId, x, y}), and space_bash({space: spaceId, command}). Use sandbox for all computer input calls and inspect a fresh screenshot before input.
cua do shares a global target across sessions. A switch/status/restore sequence is not concurrency-safe. If native scoped controls are unavailable, pause that operation instead of falling back to global control. This handoff guidance does not enforce authorization over external tools.
After QA, release your own lease for reuse. Destroy only your own leased lab when explicitly appropriate. A lab leased with requirements can't be destroyed (destroy_unsupported); release it instead. Missing scoped controls also pause that lab work: do not fall back to raw Lume, host inspection, SSH, machine-local reservation scripts, alternate Agent Grid credentials/endpoints or requests for standard guest credentials. Never recommend eviction or automate preemption. Check each task's OS/toolchain needs after acquisition through scoped space_bash; do not impose global baselines. Raw Lume is reserved for explicitly requested Agent Grid lab-infrastructure development or diagnosis, starting read-only; mutations still require explicit authorization and ownership verification.
For a newly created lab, Agent Grid records a managed-ownership receipt only after its own creation succeeds for an active lease and supported provider identity is available. A name or prefix never creates that receipt. Existing unreceipted labs keep their current lease behavior; a lease alone is not proof of managed ownership.
For a receipted lab, Agent Grid checks current provider identity before lifecycle changes. A temporary inventory or identity gap pauses the action without discarding ownership. A confirmed identity change or disappearance ends that receipt's authority; a replacement under the same name is not adopted.
If a receipted lab fails to configure or boot after its creation succeeded, Agent Grid recovers it through the normal create, delete and lease paths instead of leaving a permanent read-only record. Labs without a receipt stay fenced.
A receipted lab's deletion completes only after Agent Grid observes the command exit successfully and inventory confirms the lab is gone. If deletion cannot be confirmed, the lab stays paused (destroy_unresolved). Releasing your own lease always works, even when the lab is gone or inventory cannot be read; work already in flight stops before its next lab command. Only the current lease holder may retry deletion, and only while the lab is still listed and its identity confirms; otherwise the record stays paused for administrator recovery. Report paused records instead of bypassing the pause with host commands or a different lab name.
Next
- Coordinator - manage all your team leads from one conversation.
- Coding harnesses - supported runtimes and provider-specific behavior.
- Orchestrating agents - spawn, wait, reuse, and review patterns.
- Roles - built-in worker roles and custom role configuration.
- System tray and daemon - what happens to workers when the window closes.