The Manager Surface
The Manager Surface is Antigravity's control centre for multi-agent work. It is a dedicated panel — separate from the code editor — where you observe, steer, and review all running and completed agents. This module covers every feature of the Manager Surface in depth, including monitoring, task queues, artifact management, and debugging agent interactions.
If Antigravity's agents are the musicians, the Manager Surface is the conductor's podium. It gives you complete visibility into what every agent is doing, has done, and needs from you — without requiring you to open any code files. Experienced Antigravity users spend as much time in the Manager Surface as in the code editor, because this is where the high-leverage decisions happen: steering agents, answering clarifications, and approving or rejecting diffs.
Open the Manager Surface with Ctrl+Shift+M (Windows/Linux) or Cmd+Shift+M (macOS). It opens as a panel within the Antigravity window — you can dock it to the side, bottom, or float it as a separate window. Most developers dock it on the right side at 1/3 width, keeping the code editor visible on the left.
Anatomy of the Manager Surface
The Manager Surface is divided into four distinct areas, each serving a specific purpose:
Agent List (Left Panel)
A vertical list of all agents — running, waiting, and completed. Each entry shows the agent's name, status badge (RUNNING, WAITING, REVIEW, DONE, FAILED), task summary, and model. Click any agent to see its detail view in the main panel. Active agents pulse with a subtle animation; completed agents show a static checkmark.
Agent Detail (Centre Panel)
The main view showing the selected agent's full timeline, current action, and any clarification questions. This is where you monitor progress, answer questions, and review output. The detail view updates in real time as the agent works — you can watch files being read, code being written, and tests being run.
Diff Queue (Tab)
A tab in the centre panel that shows all completed agents' diffs awaiting your review. Diffs are listed in completion order. Each diff shows: files changed, lines added/removed, test results, and any artifacts (screenshots, reports). Click a diff to review it in a standard side-by-side diff viewer.
Artifacts Panel (Right Panel)
A collapsible panel showing all artifacts generated by agents: implementation plans, test reports, screenshots, error logs, and task breakdowns. Artifacts are grouped by agent. You can expand any artifact to view it inline, or open it in a new tab. Artifacts persist after the agent completes — they are a permanent record of what was done.
Agent Timeline — Understanding What the Agent Did
Action Log
Every action the agent takes is logged in chronological order: files read, files created, files modified, terminal commands executed, test results, and clarification questions. Each entry has a timestamp and a status icon (checkmark for success, arrow for in-progress, question mark for waiting, X for failure).
Step Replay
You can click any step in the timeline to see the state of the agent at that point: what it had read, what it had written so far, and what its plan looked like. This is invaluable for understanding why the agent made a particular choice — you can trace its reasoning step by step.
Token Usage
Each timeline entry shows the token count for that step. At the bottom of the timeline, a summary shows total tokens consumed by the agent. This helps you understand cost (for paid models) and identify tasks that are consuming disproportionate context.
Time Tracking
Each step shows its duration. The timeline summary shows total elapsed time from dispatch to completion. This helps you benchmark agent performance and identify tasks that take longer than expected — a sign that the task description may need refinement.
Steering and Clarification
One of the most powerful features of the Manager Surface is the ability to steer running agents without restarting them. This is Antigravity's answer to the problem of mid-task course correction — the agent does not need to start over when it needs guidance, and you do not need to re-write the entire task description. Steering is a conversation between you and the agent, happening in the Manager Surface while the agent works:
Agent Asks a Question
When an agent encounters ambiguity it cannot resolve from the codebase or task description, it pauses and surfaces a question in the Manager Surface. The agent's status changes to WAITING and the question appears in a highlighted box. You see a notification in the agent list — WAITING agents always float to the top so you do not miss them.
You Answer in Plain Text
Type your answer in the reply box below the question. Be specific — the agent uses your answer as additional context for the remainder of the task. For example: "Whole-order returns only for now. We can add item-level later." or "Use the existing OrderStatus enum, do not create a new one."
Agent Continues
After you answer, the agent resumes execution from where it paused. It incorporates your answer into its context and continues the plan. No work is lost — the agent picks up exactly where it left off, with your clarification added to its understanding.
You do not have to wait for the agent to ask a question. At any time, you can click "Add Instruction" on a running agent to provide additional context or redirect the agent. For example, if you see the agent heading in the wrong direction in the timeline, you can add: "Actually, put the new endpoint in routes/v2.py, not routes/v1.py." The agent pauses, reads your instruction, and adjusts its plan.
Best Practices for Answering Clarifications
The quality of your answers to agent questions directly affects the quality of the agent's output. Here are guidelines for effective clarification responses:
| Do | Do Not | Example |
|---|---|---|
| Be specific and decisive | Give wishy-washy answers | Good: "Whole-order returns only." Bad: "Maybe partial returns could work too, but for now whole-order is probably fine I guess." |
| Reference specific code | Speak abstractly | Good: "Use the existing OrderStatus enum from schemas.py." Bad: "Use whatever status type makes sense." |
| State constraints | Leave decisions open-ended | Good: "Max 100 characters, stored as VARCHAR, required field." Bad: "Add a message field." |
| Answer promptly | Leave agents blocked for hours | Check the Manager Surface every 5-10 minutes. WAITING agents should be your top priority. |
| Provide business context | Assume the agent knows your domain | Good: "We only support GBP currency — no multi-currency." Bad: "Use the right currency." |
Monitoring Agents Effectively
With multiple agents running, you need a monitoring strategy. Here are the key indicators to watch:
| Indicator | Where to Find It | What It Tells You | Action Required |
|---|---|---|---|
| WAITING status | Agent list (floats to top) | Agent is blocked on a question | Answer the question promptly — a blocked agent wastes time |
| Progress bar stalled | Agent card in list | Agent may be stuck in a loop (reading/writing repeatedly) | Open the timeline, check for repeated actions, add a steering instruction |
| FAILED status | Agent list (red badge) | Agent encountered an unrecoverable error | Read the error in the timeline, fix the issue, re-dispatch a new agent |
| High token count | Timeline summary | Agent is consuming excessive context | Task may be too broad; break it into smaller sub-tasks |
| Test failures in timeline | Agent detail panel | Agent's code does not pass tests (may still be iterating) | Wait — the agent may fix it automatically. If it does not, add guidance |
| REVIEW status | Agent list (green badge) | Agent has finished and queued a diff | Review the diff in the Diff Queue tab |
Task Queue Management
When you have more tasks than you want to run concurrently (or more than the 8-agent limit), use the task queue:
Queuing Tasks
Write all your tasks in Mission Control but only dispatch some of them. The rest sit in a "Queued" state. When a running agent completes, you can dispatch a queued task with one click. The queued task inherits the latest codebase state, including any accepted diffs from earlier agents.
Auto-Dispatch
Enable "Auto-dispatch on completion" in Mission Control settings. When a running agent finishes and its diff is accepted, the next queued task automatically dispatches. This creates a pipeline: agents run continuously, limited only by your review speed.
Priority Ordering
Drag tasks in the queue to reorder them. Higher-priority tasks dispatch first when a slot opens. This is useful when you have a mix of critical fixes and nice-to-have improvements — critical fixes should always jump the queue.
Manager Surface — Agent Awaiting Input
POST /returns/initiate support partial returns (individual items from an order) or whole-order returns only? This affects the request schema and the order lookup logic.Artifact Management
Agents generate artifacts alongside code. These are not just decorative — they serve as verifiable evidence of what the agent did and why:
| Artifact Type | When Generated | What It Contains | How to Use It |
|---|---|---|---|
| Implementation Plan | Before execution begins | Step-by-step plan showing which files will be read, modified, created | Review before dispatching to catch wrong assumptions early |
| Task Breakdown | After plan approval | Detailed sub-tasks the agent will execute, with file paths and function names | Verify the agent's understanding matches your intent |
| Test Report | After running tests | Test output: pass/fail counts, failure messages, coverage stats | Quick verification that the agent's code works; look for edge cases in failures |
| Screenshot | After browser actions | Visual capture of the web page at the moment of the action | Verify UI changes visually; share as evidence with teammates |
| Error Log | On agent failure | Full error traceback, agent's diagnostic notes, suggested fixes | Diagnose why an agent failed; use the error to write a better task description |
| Diff Summary | On completion | Plain-language summary of all changes made, with file-level detail | Quick overview before diving into the full diff; good for PR descriptions |
Agent artifacts are surprisingly useful for documentation. The implementation plan and diff summary can be copy-pasted into PR descriptions. Screenshots serve as visual proof of working features. Test reports confirm behaviour. Many teams find that agent-generated artifacts reduce the time spent writing PR descriptions by 80% or more.
.antigravity/artifacts/ within your project directory. They persist across Antigravity sessions. If you want to include artifacts in your git repository (e.g., screenshots for documentation), move them to a tracked directory and commit them. Otherwise, add .antigravity/ to your .gitignore to keep artifacts local-only.
Integrating the Manager Surface into Your Workflow
The Manager Surface works best when you integrate it into your natural workflow rather than treating it as a separate activity:
Experienced Antigravity users develop a rhythm: dispatch agents, work on other tasks, glance at the Manager Surface every few minutes, answer clarifications immediately, review diffs as they arrive, commit after each acceptance. This rhythm becomes natural within a few days of use.
Reviewing the Diff Queue
Agent completes → diff queued
When an agent finishes, its changes appear in the Diff Queue tab of the Manager Surface. Status changes from RUNNING to REVIEW. A notification badge shows the number of diffs awaiting review.
Review file by file
The diff viewer shows each changed file with standard green/red highlighting. Click any file in the left panel to review it. Artifacts (test reports, screenshots) are shown in a separate tab alongside the diff. The diff view supports both unified and side-by-side modes — toggle with the button in the top-right corner.
Accept, reject, or partially accept
Accept the whole diff, reject it entirely, or use hunk-level selection to accept individual changes. You are not locked into all-or-nothing. Partially accepted diffs show green (accepted) and grey (skipped) indicators on each hunk.
Changes applied to working tree
Accepted changes are written to your files immediately. Antigravity does not commit automatically — you commit when you are ready, giving you full control over your git history. A notification confirms: "Agent 2 diff accepted — 3 files changed, 47 lines added."
Debugging Agent Interactions
When an agent produces unexpected output, the Manager Surface provides several debugging tools:
Timeline Replay
Click any step in the agent's timeline to see the full context at that point: what the agent had read, what it had written, and what its reasoning was. This is like stepping through a debugger — you can trace exactly where the agent's understanding diverged from your intent.
Context Inspection
Click "View Context" on any timeline step to see exactly which files and code sections the agent had loaded in its context window at that moment. This reveals whether the agent missed a relevant file or misread a function signature.
Re-dispatch with Corrections
If an agent produces a wrong result, click "Re-dispatch" to create a new agent with the same task description plus your corrections. The new agent starts from scratch but benefits from your additional guidance. The failed agent's timeline is preserved for reference.
Compare Agents
Select two agents and click "Compare" to see a side-by-side view of their timelines and diffs. This is useful when you dispatched two agents with similar tasks (A/B testing approaches) or when you want to understand why one agent succeeded and another failed.
When an agent produces wrong output, the instinct is to re-dispatch the same task verbatim. This usually produces the same wrong result. Instead, read the agent's timeline to understand where it went wrong, then re-dispatch with a corrected task description that addresses the specific misunderstanding. The timeline is your debugging tool — use it.
Agent Lifecycle and Status Transitions
Every agent in the Manager Surface follows a predictable lifecycle. Understanding these transitions helps you monitor agents effectively:
QUEUED → PLANNING
When dispatched, the agent moves from the queue to PLANNING status. During this phase, it reads your codebase, analyses the task, and generates an execution plan. Duration: 5-20 seconds depending on project size. If you enabled Plan-Only mode, the agent stops here and waits for your approval.
PLANNING → RUNNING
After planning completes (or after you approve a Plan-Only plan), the agent begins executing. It reads files, writes code, and runs commands. The timeline updates in real time. Duration: 30 seconds to 10+ minutes depending on task complexity.
RUNNING → WAITING (optional)
If the agent encounters ambiguity, it pauses and surfaces a clarification question. The agent remains in WAITING status until you answer. WAITING agents float to the top of the agent list so you never miss them. You can also force a RUNNING agent into WAITING by clicking "Pause."
RUNNING → REVIEW
When the agent completes its task (plan finished, tests passing), it transitions to REVIEW status. Its diff is queued in the Diff Queue. The agent is done — it will not execute any more actions. Your job now is to review the diff.
REVIEW → DONE or REJECTED
After your review, the agent moves to DONE (diff accepted) or REJECTED (diff discarded). Both states are terminal — the agent is finished. DONE agents are greyed out in the list. REJECTED agents show a red indicator. Both timelines remain accessible for reference.
RUNNING → FAILED (error path)
If the agent encounters an unrecoverable error (model timeout, context overflow, repeated test failures it cannot fix), it transitions to FAILED. The error log is saved as an artifact. You can read it, improve the task description, and re-dispatch a new agent.
Advanced Manager Surface Features
Agent Pinning
Pin important agents to the top of the agent list by clicking the pin icon. Pinned agents stay at the top regardless of status. This is useful when you have many agents and want to keep the most critical ones visible — for example, pinning a high-priority bug fix while lower-priority tasks scroll below.
Search and Filter
The agent list supports filtering by status (RUNNING, WAITING, REVIEW, DONE, FAILED) and searching by task description keyword. When you have dozens of completed agents, filtering to "REVIEW" shows only diffs that need your attention. Searching for "checkout" shows only agents related to checkout tasks.
Bulk Actions
Select multiple completed agents and perform bulk actions: "Accept All" (accept all selected diffs), "Reject All" (discard all selected diffs), or "Export Summaries" (download all diff summaries as a single document). Use bulk actions carefully — always review diffs individually before bulk-accepting.
Agent History
The Manager Surface maintains a history of all agents from your current session. After closing and reopening Antigravity, previous session agents are archived but still accessible via Settings → Agent History. This is useful for reviewing what work was done yesterday or last week.
Manager Surface Keyboard Shortcuts
| Action | Shortcut |
|---|---|
| Open Manager Surface | Ctrl/Cmd + Shift + M |
| Switch to next agent | Ctrl/Cmd + ] (right bracket) |
| Switch to previous agent | Ctrl/Cmd + [ (left bracket) |
| Jump to first WAITING agent | Ctrl/Cmd + Shift + W |
| Accept current diff | Ctrl/Cmd + Enter |
| Reject current diff | Ctrl/Cmd + Backspace |
| Toggle artifacts panel | Ctrl/Cmd + Shift + P |
| Add instruction to running agent | Ctrl/Cmd + Shift + I |