Agent teams

An agent team is a group of named agents led by your main session. Each teammate runs in the background, keeps its own conversation, and can be given more work later by name. The lead hands out tasks, answers questions, and pulls the results together.

Teams suit jobs where several agents need to work side by side for a while and talk to each other: one agent builds the API while another builds the client, then both adjust when one changes the contract. For a one-off side task, a plain subagent is simpler and cheaper.

Teams, subagents and workflows

	Subagent	Agent team	Workflow
Shape	One helper, one job, one report	Several named agents that stay available	A fixed plan of steps that may depend on each other
Lives	Until it reports	Until the team is ended	Until the last step finishes
Can be sent more work	Only background agents, by id	Yes, by name, any time	No
Talk to each other	No	Yes, through messages	Steps read earlier steps’ output
Best for	Searches, reviews, focused fixes	Parallel work that needs coordination over time	Fan-out jobs you can plan up front

Start a team

You do not run a command. Ask for a team in plain words and say what each member should do:

Set up a team for the payment-retries feature: one teammate on the
backend retry queue, one on the admin UI that shows retry state, and one
writing integration tests against both. Coordinate them and tell me when
everything passes.

The lead then:

creates the team with its TeamCreate tool;
starts each teammate with the Agent tool and a name (lower-case letters, digits and -, such as backend, admin-ui, tests);
sends instructions and follow-ups with SendMessage to those names;
checks who is working with ListAgents;
ends the team with TeamDelete once the work is done.

Only one team runs at a time in a session. Starting a second one is refused until the first has ended.

Pick the specialists

A teammate can be one of your custom agents, so it brings its own instructions, tool limits and model. Name the agent in your request:

Make a team: use the migration-checker agent as "db", and a
general-purpose teammate as "api". db reviews every migration api writes.

How teammates work

They run in the background. Your main session stays free while they work. Their progress shows in the agents view (← on an empty prompt), where team members are marked.
They are reached by name. A message sent to backend lands in that teammate’s inbox. A teammate that has finished its last task wakes up when a new message arrives.
They share a scratch folder. Each team gets a folder under ~/.syntic/teams/ with a tasks area the lead can use to hand around notes and task lists. It is removed when the team ends.
Their words are reports. What a teammate sends reaches the lead as an agent report, never as if you had typed it. The lead weighs it like any other tool result.

Talk to a teammate yourself

Tell the lead, and it forwards the message:

Tell admin-ui to use the existing StatusBadge component instead of a new one.

To read what a teammate has been doing, open it from the agents view with Enter.

Keep quality up with hooks

When a teammate runs out of work, the session’s TeammateIdle hooks run. A hook can:

send it back to work by blocking (exit code 2, or "decision": "block" with a reason). The reason becomes the teammate’s next instruction. This can happen up to three times in a row, then the idle is accepted;
stop it by answering "continue": false.

A hook that runs the tests before a teammate is allowed to stop:

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          { "type": "command", "command": "npm test --silent || { echo 'Tests fail. Fix them before you stop.' >&2; exit 2; }" }
        ]
      }
    ]
  }
}

Field details are on the hooks reference.

Permissions

Teammates get no more freedom than the lead. They follow the same rules as subagents (Permissions), and any permission prompt a teammate raises comes to you. To avoid a stream of prompts, allow the commands the team will need before you start (Permission rules), or run in a mode that suits the job (Permission modes).

Cost

Each teammate is a full agent with its own context, so a team of four costs roughly four times one agent doing the work alone. Teammate spend appears per agent in /cost. To cap a runaway member, give its agent definition a max-budget-usd, or set agents.defaultMaxBudgetUsd (Spend caps).

Good habits

Give every teammate the context it needs. Teammates do not see your conversation with the lead. Ask the lead to brief each one with the goal, the files involved and how to check the work.
Keep the team small. Two to four teammates is easier to coordinate than eight. More agents mean more messages and more chances to conflict.
Split by files, not by steps. Two teammates editing the same file will overwrite each other. Give each its own area, or run teammates in separate worktrees by using a custom agent with isolation: worktree.
Start with reading jobs. Research and review teams are low risk and show you how the lead coordinates before you let a team write code.
Wait for the finish. Ask the lead to report only once every teammate is done and the checks pass.

Troubleshooting

Problem	What to do
The lead used plain subagents instead of a team	Ask explicitly for “a team with named teammates”.
`TeamDelete` is refused	A teammate is still working. Wait for it, or stop it from the agents view (`x` `x`).
A second team will not start	Only one team runs at a time. Ask the lead to end the current one first.
Teammates stop too early	Add a `TeammateIdle` hook that checks the work, as above.
Teammates edit the same files	Reassign areas, or use worktree-isolated custom agents.

Background sessions Messaging between sessions