Orchestrate your coding agents

Have one agent build and another review, keep a manager for work you repeat, or fan out big changes to many agents at once. You can step in at any time, or coordinate with just one.

Download for macOS

You'll need two or more agents signed in, like Claude Code and Codex.

Hand this to your agent
Ask me about each of these, one at a time, with a suggested default:
- Task (what to build or fix)
- Reviewer (a different agent from you)
Skip any I've answered. Then sum up the plan in three bullets and wait for my go. My answers override the steps below.
If a wait times out, wait again, up to three times.

Build the task, have a different agent review it in its own thread, talk it through with the reviewer. One review round, then stop.
Guide: https://getbb.app/guides/orchestrate-coding-agents

Do these steps in order and run each check. If a check fails, stop and tell me what you saw. Don't push, open a pull request, or merge unless I ask.

1. Get a branch. If you're on the repo's default branch, create a new branch first. Run `BASE=$(git rev-parse HEAD)` and keep the value.
   Check: `git branch --show-current` isn't the default branch.

2. Build the task and commit your work.
   Check: `git status` is clean and `git log -1` shows your commit.

3. Start the reviewer in its own thread, in this worktree. Use my Reviewer answer. By default, pick a signed-in agent other than you from bb provider list.
   bb thread spawn --json --project "$BB_PROJECT_ID" --environment "$BB_ENVIRONMENT_ID" --parent-self --provider <provider-id> --title "<task>" --prompt "Task: <task>. Review git diff <BASE>..HEAD read-only. Don't edit files or commit. List each issue as serious or minor, with file and line."
   Check: the spawn returns a thread ID. If the reviewer fails to start, stop and ask me to sign in to that agent on this computer.

4. Wait for the review and read it:
   bb thread wait <reviewer-thread-id>
   bb thread output <reviewer-thread-id>
   Check: the output lists issues or says there are none. If bb later tells you the reviewer completed, just repeat your final report.

5. Fix every serious issue and commit. If a finding is unclear, ask first: bb thread tell <reviewer-thread-id> "<your question>", then read the answer with bb thread wait and bb thread output. Don't ask for a second review.
   Check: `git status` is clean and each serious issue has a fix.

6. Stop. Leave the reviewer's thread open so I can read it; don't archive it.

Reply with what you built, what the review found, what you fixed, and what's left for me. Then offer to save these steps as a bb skill in .bb/skills/build-and-review/SKILL.md, with my reviewer filled in, so next time I can just ask for it.

Steps

  1. 1Start a thread with your task
  2. 2Get a second opinion from another agent
  3. 3Watch them talk it through
  4. 4Keep a manager for work you repeat
  5. 5Wake it every morning
  6. 6Fan out a big change with a workflow
1

Start a thread with your task

Pick the agent you want building it. It writes the code, brings in a reviewer, and reports back to you.

  1. Choose New thread, pick the agent, and choose Worktree so the work gets its own branch.
  2. Paste the prompt from and send it. Your agent asks for your task and reviewer.
2

Get a second opinion from another agent

A different agent reads the change with fresh context and catches what the first one missed. You don't copy anything between them.

Once its work is committed, your agent starts the reviewer in a thread of its own, on the same branch, and nests it under itself in the sidebar. You can ask for any agent by name, like “Have Codex review this” or “Ask Cursor to write the release notes.”

3

Watch them talk it through

The agents message each other the way you message them. Your agent hears back as soon as a review is done, and fixes what's serious.

  1. In the sidebar, open the reviewer's menu and choose Open in split.
  2. Type in either thread to step in yourself.

Ask the reviewer a question through your agent

Ask your agent to check something with the reviewer, like “Ask the reviewer whether the memory growth is worth fixing before this merges.” It asks, waits for the answer, and tells you what it said.

4

Keep a manager for work you repeat

A manager is a thread you keep for one job, like triaging new issues. Correct it once, and it does the job your way from then on.

  1. Start a thread and name it after the job, like Issue triage.
  2. Walk it through the job once, like where new issues land and how you rank them, and correct it as you go.
  3. Ask it to save the job as a skill, a saved set of instructions it reuses.
Ask the manager
Save how you triage issues as a skill called issue-triage in this repo. Run it every time I ask for triage, and update it whenever I correct you.

Hand it work by dragging

Drag any thread onto the manager in the sidebar to nest it there, then ask the manager to take the next step, like opening a pull request and watching CI. It doesn't have to be the agent that did the work.

5

Wake it every morning

An automation messages the manager on a schedule, so every run lands in the same thread and builds on the last.

Ask the manager to schedule itself.

Ask the manager
Every weekday at 9am my time, have an automation message this thread and ask you to run your issue-triage skill. Run it once now to test it.

Open Automations to see its schedule and runs, or switch it off. Run an agent on a schedule covers testing a run and notifications.

6

Fan out a big change with a workflow

For a big, repetitive change, like fixing one lint rule across a whole codebase, a workflow starts a worker for each part of the job and checks the results.

  1. Open Settings → Installed plugins and turn on Workflows. It's off by default.
  2. Ask your agent for a workflow by name.
Example
Use a workflow to fix every no-floating-promises lint error. Start one Codex worker per top-level folder, then have a Claude Code worker check each folder's fixes. Open one PR when every check passes.

The run shows in the thread with each worker's progress. To stop it, open the run in the side panel from its card above the message box, and choose Stop workflow.

Troubleshooting

My agent didn't bring in a reviewer
  1. Agents only start other threads when you ask. Check that the prompt from Copy for agent is in your first message.
  2. Or ask directly, naming the agent and the job, like “Have Codex review this branch, read-only.”
The reviewer's thread failed right away
  1. Open the reviewer's thread and read the error.
  2. Usually that agent isn't signed in on this computer. Sign in to it once, like codex login for Codex.
  3. Send the reviewer's thread a message to start it again.
My agent never heard back from the reviewer
  1. Check the sidebar. Your agent only hears from threads nested under its own.
  2. If the reviewer sits on its own, drag it onto your agent's thread.
  3. Then tell your agent the review is ready, so it reads it now instead of waiting.
The reviewer is stuck waiting
  1. It's asking a question or waiting for permission to run something.
  2. Open its thread and answer it. Your agent is told it's waiting.
Both agents changed the same files
  1. They share one worktree, so they share files. Tell the reviewer to stay read-only, as the prompt from Copy for agent does.
  2. If both need to write, have them take turns, or ask for the second agent in its own worktree.
The reviewer can't see the changes
  1. It started in a separate worktree, so it can't see work that isn't committed.
  2. Ask your agent to commit, then start the reviewer in this same worktree, as the prompt from Copy for agent does.
The reviewer's thread disappeared

If it was archived, open Settings → Archived threads and choose Unarchive.

My agents stopped while my computer slept
  1. Once the computer is back, open the thread and send a message to pick up where it left off.
  2. To keep it awake, open Settings, choose Keep Awake under Plugins, and turn on Prevent idle sleep. It works on macOS and Windows.
  3. Closing a laptop's lid still puts it to sleep. For agents that run all day, run bb on a computer that stays on.
My manager forgot a correction
  1. Long threads get compacted, and older details can drop out of the conversation.
  2. Ask the manager to add the correction to its skill, so it holds on every run.
My manager didn't run this morning

See “My automation didn't run” in Run an agent on a schedule.

My agent won't start a workflow
  1. Turn on Workflows in Settings → Installed plugins.
  2. Ask for a workflow by name. Agents don't start one unless you ask.

FAQ

When is a second agent worth it?

For most changes, one agent does fine. A second one pays off for:

  • Review. An agent on another model reads the change with fresh eyes.
  • Plan, then hand off. Have your strongest model interview you and write the plan, then hand the build to a faster, cheaper one.
Which agents work?

Claude Code, Codex, and Pi are built in. Cursor, opencode, and other agents that support the Agent Client Protocol, like Grok Build and Hermes Agent, work once they're installed.

How do agents reach each other?

Every thread comes with bb's tools and a short guide to them, so an agent can start, wait for, and message other threads the way you would. A message reaches a busy agent mid-turn, and one sent to an agent that's waiting on a question is delivered once you answer.

Can I step in?

Yes. Type in either thread at any time, or stop one from its message box. A stopped thread keeps its history and worktree. bb doesn't tell the other agent you stopped it, so let it know.

Does it cost anything? Can I keep my plan?

bb is free and open source, and bb connect is free. bb runs your agents on the subscriptions or API keys you already have. Machines you add cost what they do now.

What's the difference between a manager and a workflow?

A manager is one thread you keep for a job and talk to over days. A workflow is a single run that splits one big job across many workers and finishes.

Hand off the work you repeat

Free and open source. Bring the Claude and ChatGPT plans you already have.

Download for macOSApple Silicon · Also for Linux (Alpha)bb runs on macOS, Windows, and LinuxWindows (Alpha), Intel Macs & remote machines