How to orchestrate a team of Claude Code agents
To orchestrate a team of Claude Code agents, give them a shared place to talk and a leader. In BRIX each agent is a real terminal; you connect two of them with an edge on the canvas, and that edge is the permission to exchange prompts. A lead agent recruits workers, splits the task, follows up and reports back, using the medmaestri CLI.
What does "Claude Code orchestration" actually mean?
Running several Claude Code sessions side by side is parallelism. Orchestration is the next step: the sessions know about each other, one of them leads, and the work is split and merged without you copying text between windows.
In BRIX that takes three pieces, all on your machine: terminals running the agent CLIs you already use (Claude Code, Codex, Antigravity, OpenCode or a plain shell), edges on a canvas that decide who can talk to whom, and a small CLI, medmaestri, that the agents call to send prompts, read each other and update a shared task list.
| Parallel terminals | Orchestrated team | |
|---|---|---|
| Who splits the work | You, by hand | A lead agent |
| How agents share results | You copy and paste | ask, send and check between connected agents |
| Who can talk to whom | Nobody | Whoever is connected by an edge |
| Where progress lives | In your head | A task list card on the canvas |
How do agents talk to each other in BRIX?
BRIX owns every terminal it opens, so it runs a local broker that routes messages between them by name. Each agent gets the medmaestri command in its PATH and uses it like any other tool.
medmaestri list # agents connected to me
medmaestri ask "Backend" "Is the /orders route done?" # send and wait for the reply
medmaestri send "QA" "Run the checkout tests" # type the prompt, do not wait
medmaestri check "Frontend" --clean # read what that terminal is showing now
medmaestri wait "QA" --timeout 600 # wait until it goes idleThe edge is the permission. Two terminals only reach each other if there is an edge between them on the canvas. Without one, the broker refuses the message and tells the agent to create the link first. You draw edges by hand, or an agent creates them with medmaestri connect "A" "B" (and removes them with --remove).
This is what keeps a ten-agent workspace sane: a QA agent connected to Backend and Frontend cannot accidentally prompt the security auditor you left running in the corner.
How do I set up a lead agent that recruits workers?
This is Maestro mode: you talk to one agent, and it builds its own team. When a lead runs medmaestri spawn, BRIX opens a new terminal that is already connected to the lead, launches the CLI you chose and types the briefing in.
- 1
Open one terminal and start your agent
Run
claude(orcodex) in a BRIX terminal pointed at your project folder. This is the lead. - 2
Ask it to lead
Tell it the goal and that it should recruit helpers. The bundled
medmaestriskill teaches Claude Code and Codex the commands, so a plain request like "split this between two workers" is enough. - 3
The lead spawns workers
Each
spawnnames the worker, picks the CLI and passes the briefing.--linkalso connects the new worker to an agent that already exists. - 4
The lead follows up
It uses
askto get answers,checkandwaitto see who is done, and closes the workers it recruited withmedmaestri dismiss "Name".
medmaestri spawn --name "Backend" --cli claude --prompt "Implement the /orders routes from contract.md" --cwd ~/code/shop
medmaestri spawn --name "QA" --cli codex --prompt "Write tests for /orders as soon as Backend reports done" --link "Backend"If you prefer a fixed shape, medmaestri team creates a supervisor plus N workers in one go, each briefed and connected. The same thing is the "Create team" button in the app.
medmaestri team --supervisor claude --workers codex --count 3
# then: medmaestri ask "<supervisor name>" "<the task>"What are the ready-made squads?
A squad is a team that is born ready: every agent has a role, a briefing and edges to exactly the agents it needs. You start one from the Squads panel or with medmaestri squad <id>. Three of them are for code:
| Squad | Agents | How the work flows |
|---|---|---|
feature (end-to-end feature) | Architect, Backend, Frontend (Claude Code), QA (Codex) | Architect writes the API contract first and does not code. Backend and Frontend implement their side and agree contract changes directly. QA tests each delivery and reports to whoever broke it. |
cacabug (bug hunt) | Repro, Investigator, Fixer (Claude Code) | Repro reduces the bug to the smallest case. Investigator finds the root cause in read-only mode. Fixer is the only one who edits, adds a regression test and asks Repro to confirm. |
blindagem (review and hardening) | BRIX Guard, Cleanup (Claude Code), Reviewer (Codex) | Guard runs a security audit, Reviewer reads the diff against HEAD, and Cleanup applies both lists, most severe first, then runs the project checks. |
Two more squads, oferta (offer launch) and conteudo (content series), apply the same idea to marketing. You can also duplicate any squad, change roles, CLIs and edges, and save it as your own.
medmaestri squad list
medmaestri squad cacabugHow do I track what each agent is doing?
Put a task list card on the canvas and connect it to the lead. Each task has a title, a description and a status: pendente (pending), fazendo (in progress) or feito (done). You edit it by hand; the connected agent reads and updates it through the CLI.
medmaestri tasks list
medmaestri tasks add "Add /orders pagination" --desc "cursor-based, 50 per page"
medmaestri tasks status t1 fazendo
medmaestri tasks status t1 feito- The play button on the card sends the list to the connected terminal as a briefing, so "work through the list" is one click.
- Notes work the same way:
medmaestri note create,read,writeandeditgive the team a shared scratchpad, such as the API contract. - The Scene view turns each agent into a pixel-art character driven by the terminal's real activity, so you can see who is working and who is waiting for you without opening every pane.
Grid or canvas: which layout should I use?
| Grid | Canvas | |
|---|---|---|
| Layout | Panes rearrange themselves as terminals open and close | You position, pan and zoom freely |
| Edges | Kept, just not drawn | Drawn between terminals; drag to connect |
| Extras | Terminals only | Notes, task lists and images the agents publish |
| Best for | Two to four agents you watch closely | Squads and teams where the topology matters |
Switching layout does not restart anything. A squad started in the grid keeps its org-chart positions for when you open the canvas.
Can I drive the team from outside BRIX?
Yes. The same commands are exposed through the BRIX MCP server, so Claude Desktop, the Codex app or a Claude Code session in a regular terminal can list agents, spawn a squad, ask a terminal and update tasks. An outside client sees every terminal and creates new ones in the active workspace. See the BRIX MCP guide.
BRIX does not run the models. Every agent uses the Claude Code, Codex, Antigravity or OpenCode login you already have, so more agents means more usage of those subscriptions, not a BRIX token bill.
What does it cost and where does it run?
Orchestration, Maestro mode, squads, the canvas and the task list are all in STARTER, the full agent environment. PRO adds the marketing studios, where the same kind of team writes copy, ads, carousels and video for the product it just built. Both start with 7 days free, no card. See plans and download for macOS or Windows.
Frequently asked questions
Can Claude Code agents talk to each other?
Not on their own: each Claude Code session is isolated. In BRIX they can, through the local medmaestri CLI, as long as an edge on the canvas connects the two terminals.
Can I mix Claude Code and Codex in the same team?
Yes. Each terminal runs its own CLI, and the built-in feature and blindagem squads already pair Claude Code builders with a Codex tester or reviewer. See Claude Code and Codex together.
What stops an agent from messaging every other agent?
The edges. The broker only delivers ask, send and check between terminals connected on the canvas, and refuses everything else.
Do I need to write the orchestration code myself?
No. BRIX installs a medmaestri skill for Claude Code and Codex that teaches the commands, so you ask the lead in plain language and it calls spawn, ask and tasks itself.
Can I create my own squad?
Yes. Duplicate a ready-made squad or start from scratch in the Squads panel, set each agent's role, CLI and briefing, draw the edges and save it.
Keep reading
- How to run multiple Claude Code agents in parallelHow to run multiple Claude Code agents in parallel: terminal tabs, tmux, git worktrees, Conductor, Claude Squad, and connected agents with a lead in BRIX.
- How to use Claude Code and Codex togetherHow to use Claude Code and Codex together in one workspace: one writes, the other reviews, and they message each other between terminals with medmaestri.
- BRIX MCP: operate BRIX from Claude Desktop, Codex or Claude CodeOperate BRIX from Claude Desktop, the Codex app or Claude Code with the BRIX MCP server and the medmaestri CLI: spawn agents, send prompts, build squads.