Example teams, how to write good roles and instructions, and troubleshooting.
A team pays off when a job has independent parts, or when a part needs a lot of reading you do not want in the main conversation.
| Good fit | Poor fit |
|---|---|
| "Find every place that uses the old API, then review the migration." | "Rename this variable." |
| "Run the tests and, in parallel, check the docs for outdated examples." | A change where each step depends on the previous one. |
| Large codebases where exploring is most of the work. | A quick question about one file. |
The lead decides for itself, so for small jobs it works alone. You can also be explicit: "Use the Researcher for this" or "Do this yourself, no bots."
| Bot | Access | Model | Role |
|---|---|---|---|
| Researcher | read | fast, cheap | Finds code and reports file paths with line numbers. |
| Reviewer | read | strong | Reviews the changes the lead made. |
The lead sends the Researcher to map out the code, writes the change itself, then gives the diff to the Reviewer. Because both bots are read-only, they never need an approval.
| Bot | Access | Role |
|---|---|---|
| Tester | read, run commands | Runs tests and the type checker and reports failures with causes. |
| Writer | read, edit | Updates docs and changelog entries for the change. |
After a change, the lead hands the testing and the documentation to two bots at once and finishes when both have reported.
You can let bots hand work on. Allow Researcher → Reviewer, and the Researcher can ask the Reviewer to double-check its findings before it reports. Keep chains short: the depth limit is 2. See How hand-offs work.
The role is a routing label. Write it as what the bot does and returns, in one sentence, and say what it does not do.
Runs the project's tests and type checks and reports each failure with its likely cause. Does not change code.Testerbun run test).The lead is a model like any other: clear requests give clear delegation.
The lead never uses the team. Check that the lead has the bots ticked (select Lead in the graph). Make each bot's role specific, and mention the bot in your request. Small jobs are done by the lead itself on purpose.
The run seems stuck. A bot may be waiting for approval. Approvals appear in the chat, not on the team page, and are shown one at a time. Switch to the chat. If you did not mean to wait, use Auto approval or stop the run.
A bot says it cannot do something. It probably lacks the tool. Open the bot, tick Edit files or Run commands, and click Save. Changes apply from your next message.
"The teammate used up its steps before finishing." A bot has 25 steps. Give it a narrower task, or split the job between two bots.
Reports are cut off. They are capped at 8,000 characters. Ask the bot to summarise and to list only what matters.
My changes to a bot did nothing. You must click Save, and the new settings apply from the next message you send, not to a run in progress.
"Your team is full (12 bots)." Delete a bot you do not need, or merge two roles.
A bot disappeared from my team.
If .peridot/team.json is edited by hand and a bot has an invalid or duplicate id, Peridot drops it when loading. See The team file.
The page says Open a project first. Teams belong to projects. Add a project folder with + next to Projects in the sidebar.