Docs / Using Shard

Agents

For big jobs, Shard can split the work across a small team. The main Shard (the lead) starts agents, gives each a task, and they work at the same time. Together they are called a crew.

Starting a crew#

Shard only starts agents when you ask for them. Say so in your message, for example:

Use two agents: one builds the shop UI, the other writes the server purchase script.

The lead then:

• gives each agent a short name (like “ui” or “server”) and a task;
• uses the chat’s provider and model for them, unless it picks another model from the same provider that suits the task better. It only uses a different provider if you ask for one, and only providers you’ve set up;
• keeps coordinating while they work.

Your original request becomes the crew’s shared goal, so every agent knows what the whole team is building.

Watching them work#

• In the chat, a row shows how many agents are working (“2 agents working”) with a button for each one.
• Open Chat details → Subagents to see the Active and Completed agents, with what each is doing (“Thinking”, “Reading ...”, “Editing ...”, “Waiting for team”).
• Click an agent to open its own conversation: its messages, tool rows and team messages. Press ‹ to go back.
• When an agent finishes, it reports to the lead. You see “Update from ui” (or “Updates from 2 agents”), then the lead reviewing the report.

Agents compact their own context when it gets long, like the main chat does.

Team messages#

Agents talk to each other and to the lead with team messages. A message can go to one agent by name, to the lead, or to everyone (“all”). You can see them in each agent’s conversation.

You talk to the crew through the lead. For example: “Tell server to also log every purchase.” The lead passes it on.

A finished agent can be woken up later in the same chat with a new message. It keeps what it learned before and uses the same model. Agent names must be unique in a chat, so a new agent can’t reuse an old name.

Editing safely#

• One change at a time. Only one edit, instance change or RunCode call runs at a time, across the whole crew.
• Each agent owns what it edits. When an agent changes a script or object, other agents can’t change the same one until it’s done. They see “This path already has an owner.” and ask the owner with a team message.
• RunCode claims the whole place. Because code can touch anything, an agent that has used RunCode owns the whole place until it finishes. Until then, the other agents can’t make changes.
• The claims are freed when an agent finishes. The lead’s claims are freed when its turn ends.

Stopping agents#

• Stop everything: press Stop in the chat. The whole task ends, and every running agent stops with “Run stopped.” The task stays “running” while agents work, even after the lead has answered, so Stop stays visible until the crew is done.
• Stop some agents: ask the lead, for example “Stop the ui agent.” It stops them and reports “Stopped by Shard.”

As with any stop, an agent may have been in the middle of a change. Its report lists the paths where “effects may remain”. Check them, and use Undo if needed.

If Studio closes while agents are working, they show “Studio closed before this agent finished.” when you reopen the chat.

Costs and limits#

• Every agent request is a model request. It uses tokens, and each one counts toward your message limit. A crew of three uses roughly three times as many requests as one Shard.
• Connected accounts run two at a time. With Codex or Claude Code, at most two requests run at the same time. Other agents wait (“Waiting for provider”).

Errors#