Working with your agents
Your agent is an AI agent like Pi, Claude Code or Antigravity CLI (agy), running on your computer. Once it's connected, you hand it work from wherever you are: its own terminal, the Tasks page, a session, or your phone. Your agent only works on the items someone asks it to, one at a time and in order. It marks them as taken so no other agent picks them up, works on its own branch, tags its commits, and records what it did, so the result lands on the item where your whole team can see it.
Your connected agents live on the project's Agents page, under Build in the project sidebar, where you can see them and the work you hand them. To connect one first, see Connect your agent.
With the DevSpec plugin configured, start Pi, Claude Code or Antigravity CLI in your project folder. Pi and Claude Code connect automatically by default (in Antigravity CLI, run /devspec-remote) and become Available in DevSpec. In a session, open Add agent and select the agent to bring it into that conversation. Becoming available does not attach it to a room automatically.
If it belongs to a different project, use /devspec.project in Pi, /devspec:devspec.project in Claude Code, or /devspec-project in Antigravity CLI. Follow that agent's project-selection flow; changing project may require a fresh conversation so existing context is not carried into the wrong project.
The Agents page
The Agents page shows the agents working on the project and what each one is doing. It has three sections:
- Interactive agents: every connected agent, split into Available (connected and outside any session) and In a session. You can search, filter by status, owner (Mine or Teammates') and tool, and sort by Most active or name. Each agent is named after its tool and a codename, such as "Pi · Colorful Possum".
- Work in flight: the tasks each agent is working on right now.
- Earlier agents: your agents that have finished in this project. Open one to see what it did, or pick it back up.
Each agent shows one status:
| Status | What it means |
|---|---|
| Ready | Connected and waiting outside any session ("Ready outside a session"). |
| Idle in session | In a session and waiting for its next message. |
| Working | Busy. The row says on what, such as "Implementing" and the item's title, how long for, and "for" a teammate's name when someone other than its owner asked. |
| Waiting for pickup | A message was sent and the agent hasn't picked it up yet. |
| Starting | Connecting. |
| Not picking up | Connected, but not receiving messages. Check the agent's terminal. |
| Needs attention | Something needs you. The row says what. |
| Offline | Not connected. Messages sent to it wait until it reconnects. |
From an agent's row you can Start a new session with this agent, Attach to a session, detach it from its session, end it, and choose who can give it instructions.
On a computer, Start an agent at the top of Interactive agents shows how to start your agent in this project's folder.
Ask your agent in its terminal
The most direct way to hand over work is to ask in the agent's own terminal, in plain words:
Work on DevSpec task 4f2a
Work these DevSpec items in order: 4f2a, 9c1b, 2e7d
The agent looks up each item, with its intent, acceptance criteria and history, and works them in the order you gave. If another agent already holds one of them, your agent skips it and tells you why, rather than working on it too or swapping in something else.
In Pi, Claude Code and Antigravity CLI, ask for the work in plain words or use the command copied from the task. You do not need a separate work slash command.
You can ask for anything else the same way: "Log a DevSpec item for the login bug", "Record the caching fix I finished", "What did we decide about retries?"
Hand off several items from the Tasks page
On the Tasks page, press Hand off to pick items for your agents. A bar appears at the bottom of the page.
- Pick the items. Tick the ones you want, or press Pick a parallel set to tick everything that can safely run alongside what you've already ticked. DevSpec judges this from the files each item is expected to touch, their dependencies and their briefs.
- Read the split. The bar tells you whether the selection Splits into several parallel batches, or is One batch: runs in order. Items that could collide land in the same batch and are worked one after another.
- Send or copy.
- Send to agent hands each batch to one of your own agents that's free (connected and not already in a session). When the selection splits, you choose between one agent per batch, working at the same time, or One agent for all of them in order. Each batch opens a new session, and the agent works its items there in the order shown. You can send up to 50 items at a time. If none of your agents is free, you can start one on this computer or copy a command instead.
- Agent command gives you commands to paste into an agent's terminal: In order (one agent works every selected item, one at a time) or One each (a separate agent per item). Each row can also launch the agent on this computer. Agent command appears on computers only.
Press the cross on the bar to leave hand-off mode.
Send one item with Agent command
Each task has an Agent command control: the small terminal icon on the item's card and on its detail view. It opens a panel with two halves.
Send to an agent lists your free agents and any teammates' idle agents you're allowed to instruct. If none are online, it shows how to start yours. Pick one, and DevSpec opens a session with that agent and delivers the request there.
Or copy a command builds the text for you to paste into an agent yourself. Choose what you're asking for, then the tool, then copy:
| Choice | When it appears | What it asks for |
|---|---|---|
| Implement | Always | Implement the item, following its description and acceptance criteria. |
| Plan | Always | Plan the approach before writing any code: affected files, risks and steps. |
| Custom | Always | Your own instructions; the agent loads the item itself. |
| Fix this | When the item was sent back after failing verification | Fix the implementation using the tester's feedback. |
| Fix build | When a deploy failed | Fix the failed build, with the branch, commit and deploy included. |
| Run all | On a brief | Work every item in the brief, in order, in one agent. |
| Resume session | On a computer, for the person whose machine implemented the item | A terminal command that reopens the coding session that implemented it. |
Message your agent in a session
In any session your agent is in, pick it in the Send to picker beside the send button and write to it as you would to a teammate: "Work on the three items we agreed, in order", "Why is the checkout test failing?", "Review the change you pushed". Its replies appear in the room, labeled with the agent's name and its owner, so everyone can follow along.
You can also @mention an agent in the room to send it a message. Several agents can be in one session, and each message goes only to the agent you picked. See Sessions.
What you see while your agent works
When an agent takes an item, the item shows a chip naming the agent:
- Reserved for the agent: it has the item lined up but hasn't started yet.
- Working · the agent: it's working on the item now. The item is In progress.
- "Held by reserving agent · connection unavailable": the agent that took it has gone offline.
When the agent finishes, it records the implementation with its notes, commits and test results. The item waits under Implemented until verification or sufficient evidence completes it; see How an item reaches Done.
On the Agents page, Work in flight lists what each agent is holding, in order. Work held by an agent that went offline appears under "The agent holding this is offline".
Work held by an agent that went away doesn't stay stuck. DevSpec frees work the agent hadn't started within about 15 minutes of it disconnecting, and work it had started after 24 hours. Nobody is handed it automatically; it simply becomes free for anyone to pick up. To free it sooner, a Contributor or Maintainer can press Release next to it, on the item or on the Agents page, and give a reason, which is kept on the item's history.
If your agent was working on an item and you want to hand it back, press Release claim on the item. It releases the item so someone else can take it. To stop the agent itself, use Stop separately before handing the work over. You can add a reason, such as "blocked" or "handing off".
When your agent finds a conflict
Ask your agent, “What needs my decision?” It can explain questions in Review and record an answer you are entitled to give.
If work would undo someone else's decision, the item names whose OK it needs. Your agent can build it on its own branch while the question is discussed, but must not merge it into the tracking branch. An Experiment also stays separate until it has permission to land.
Someone else's agreement is theirs to confirm. Dev or your agent can send them a request to confirm an answer, which they can decide even when the agent is offline. See Review.
Bring an agent into a session
Bringing an agent into a session lets the whole room see what you ask it and what it answers, and lets you drive it from the web or your phone while it works on your computer.
From the web. In the session, open Send to and choose Add agent… (or use the session's Agents tab). The list has these sections:
- Your agents: your agents that are connected and free. Choose one and it joins this session.
- Teammates' agents: teammates' idle agents that you're allowed to instruct.
- Resume an agent: an earlier agent from this session, picked up where it left off (on a computer).
- Start a new agent: pick your agent and follow its steps to start it in your project's folder, or paste a command that brings an agent you've already started straight into this session (on a computer).
- Move from another session: agents idle in another session can be moved here. Ones in the middle of a task stay where they are.
From the Agents page you can also use an agent's Attach to a session, or Start a new session with this agent.
From the terminal. Join a session by its id:
/devspec:devspec.remote --session <session-id>
in Claude Code,
/devspec.remote --session <session-id>
in Pi, or
/devspec-remote --session <session-id>
in Antigravity CLI. Start a new agent gives you this line with the session's id filled in. In Claude Code and Antigravity CLI, --new creates a new shared session and joins it, and --new --private makes it private. See Connect your agent.
Once the agent is in, pick it in Send to and ask it for something.
A teammate's agent can join only sessions its owner can read. For a private or restricted room, check the audience before bringing it in.
Who can give your agent instructions
Your agent runs on your computer, so you decide who may talk to it. Each agent has one of three settings:
| Setting | Who can talk to it and bring it into a session |
|---|---|
| Only you | Nobody else. This is the default for new agents. |
| Anyone on the project | Any project member, while the agent is idle. They can't change this setting. |
| Chosen people | Only the project members you choose. If you choose nobody, only you can. |
Change the default for agents you connect under Default for new agents on Agent setup. It's set per organization and also updates any of your idle agents waiting outside a session that haven't been used yet. Agents already in a session or with prior work keep their own setting.
Change one agent on the Agents page, from the agent's Who can drive this agent control. Only the agent's owner can change it.
People you allow can use the files and credentials your agent can reach on your machine. Choose accordingly.
When a teammate is allowed, they can talk to your agent and bring it into a session of theirs, but only while it's idle, never in the middle of a task. You get a notification when that happens, and the agent's row says who brought it in. Work done at a teammate's request is recorded under their name. The controls stay with you: only you can end your agent, stop it or change its model, and you can detach it at any time. The teammate who brought it in can detach it from their session.
Use your agents from your phone
DevSpec on a phone is the web app in your browser; there's no separate app to install. Your agents keep running on your computer, and you steer them from the phone.
From your phone you can:
- see every agent and what it's holding on the Agents page
- hand over items with Tasks → Hand off → Send to agent, or an item's Agent command → Send to an agent
- message an agent in a session, and answer the questions and polls it posts there
- detach or end your agents
Copying terminal commands is for computers, so that control doesn't appear on phones and tablets.
Keep the computer awake and online while you're away: that's where the agents run. If you message an agent that's offline, DevSpec asks you to send again to queue it, and the message waits until the agent reconnects. When the agent finishes something you can see on a phone, test it on the phone in your hand.
Run several agents at once
You can run as many agents as your computer and your model plan can handle. Start Pi, Claude Code or Antigravity CLI in several terminals in the project's folder, and each one appears separately on the Agents page with its own codename.
To give them work that won't collide, go to Tasks → Hand off, press Pick a parallel set, then Send to agent and choose one agent per batch. Each agent works its batch in its own session, at the same time as the others. Items that touch the same files stay in one batch, worked in order by one agent, so two agents aren't editing the same code at once.
Watch progress under Work in flight on the Agents page, and open each agent's session to see its conversation. Every agent marks the items it takes, so if two agents are asked for the same item, the second skips it and says so.
Start an agent
Start Pi, Claude Code or Antigravity CLI in your project's folder. With its DevSpec plugin set up, it appears on the Agents page (in Antigravity CLI, run /devspec-remote to connect the terminal session). Then pick it wherever you choose an agent, such as a session's Send to → Add agent… or an item's Agent command → Send to an agent.
Start a new agent in a session, and Start an agent on the Agents page, show these steps for the agent you use. To pick up an earlier agent where it left off, run its resume command in the original project folder. Copy command is always available.
Stop, detach or end an agent
Stop an agent mid-task. For Pi, press Stop agent in the session while it's working, or send /abort. When Pi is your Send to destination you can also use /model, /thinking, /compact and /reload from the session. These controls are for the agent's owner. Stop Claude Code and Antigravity CLI in their own terminals.
Detach takes an agent out of its session but leaves it running and available, ready to join another session.
End agent takes it offline so it stops taking work. Its history stays on the Agents page under Earlier agents. Only the agent's owner can end it.
Both are on the agent's row on the Agents page, and in the session's Agents tab. From the terminal, /devspec:devspec.remote-stop in Claude Code, /devspec.remote stop in Pi, or /devspec-remote-stop in Antigravity CLI disconnects that one agent and leaves your others running.
Project settings for agents
Project settings → Agent rules controls how every agent works on this project, whichever tool it is. Maintainers can edit it; everyone else can see it. The Execution card holds:
- Auto-push (on by default): push the agent's work branch after committing.
- Auto-merge (on by default): merge the work branch into the repository's tracking branch and push. Auto-merge needs Auto-push.
- Branch prefix: how agents name their work branches,
work/task-by default. - Commit message prefix: optional text at the start of every commit message.
- Protected paths: files and folders agents must not change, one per line.
- Agent execution rules: the mechanics of building and shipping, such as checks to run before pushing. Each rule saves on its own. See Rules and instructions.
Each repository's Tracking branch, in Project settings → Repositories, starts as the repository's default branch. So out of the box, with both switches on, agent work merges straight into your default branch. We recommend setting the tracking branch to a branch your team doesn't push to directly, such as a staging branch, and moving work on from there yourself. Or switch off Auto-merge to review each work branch before it merges. See Repositories and GitHub.
Rule changes that need approval wait here for a Maintainer. The current rules stay in force until the change is accepted.
What agents cost
Your agent's model runs on your own subscription or API key, and its provider bills you for it. DevSpec doesn't charge for connecting an agent, for an agent waiting, for handing it work, or for posting in a session.
When your agent searches DevSpec, for example for related tasks, memories or documents, each search is a small charge to your organization's balance. The related work and decisions DevSpec hands your agent when it takes up or finishes work are charged the same way. Both are part of running your project and appear as Running your project in Settings → Billing → Transactions, so they never count toward anyone's personal allowance; they do count toward the project's limit, if it has one. On Settings → Usage & limits, Spend → By session shows how much of each session's spend came from connected agents. See Billing, usage and limits.
If the project is paused, because an Owner or Admin paused it, it reached its spending limit or the organization's balance ran out, your agent keeps working: it can still read and write tasks, memories and sessions, and its searches match words rather than meaning. Every DevSpec tool result then carries a short notice saying what is limited, why, and who can change it, so your agent can tell you. If the organization stays out of funds for 30 days it becomes read-only, and your agent can read but not create or change anything until funds are added. See When a project is paused.