How to message Claude Agent Teams (lead vs teammate vs broadcast)
A practical routing playbook for Claude Agent Teams so your messages land where you intend — and you can prove where they went.
- CLI
- 0.1.0
- Preview ref
- f36aa45
The fastest way to make Claude Agent Teams feel useless is to keep sending messages to the wrong target.
It’s subtle.
You think you told the teammate to run tests, but you told the lead.
You think you broadcast a global constraint, but you sent it to one teammate.
Then you end up doing the thing teams were supposed to prevent:
- re-explaining context
- repeating yourself
- second-guessing whether anyone heard you
This guide is a routing playbook: lead vs teammate vs broadcast, and the small habits that keep messages landing where you intend.
TL;DR
- For Claude Agent Teams, always decide who you are talking to before you decide what you are saying.
- Use:
- Lead for coordination and final decisions
- Teammate for specific work
- Broadcast for global constraints
- Prefer messages that can be verified:
- ask for a one-line acknowledgement (“ack + current step”)
- ask for a checkpoint summary before a risky action
- If you want an interface that makes routing explicit, Happier is one option that helps because it has a “Send to” chip and renders routed messages as “To: …” cards.
The problem
Routing is the hidden tax of teams.
On a single-thread session, every message goes to one place.
On a team, a message is a directed action.
If you don’t make that direction explicit, you get:
- duplicated work
- missed constraints
- “why is this teammate doing the wrong thing?” confusion
What I tried first (and where I bounced off)
- Always talk to lead: safe, but it collapses the team into one agent.
- Only talk to teammates: feels fast, but you lose the coordination layer.
- Broadcast everything: creates noise and mixed responsibility.
A routing map that works
Lead (coordination)
Use lead when you want:
- a plan
- a summary
- conflict resolution between teammate outputs
- a final decision
Good lead message pattern:
Summarize what each teammate found, list the disagreements, and propose one decision.
Teammate (execution)
Use a teammate when:
- the task is clear and bounded
- the input and output can be described cleanly
Good teammate message pattern:
Do X. Stop after you finish. Reply with: (1) what you changed, (2) what you didn’t change, (3) what you need from me.
Broadcast (global constraints)
Use broadcast when:
- the message is a constraint that applies to everyone
- the message is coordination (“pause”, “checkpoint”, “stop after next step”)
Good broadcast messages:
- “Don’t touch migrations.”
- “Stop after the next step and summarize.”
- “If you’re about to install dependencies, ask first.”
Bad broadcast messages:
- “Refactor this file” (unclear owner)
- “Fix these tests” (who is responsible?)
Worked examples (copy/paste)
Example 1: broadcast a safety constraint
Don’t touch migrations or auth. If you think you need to, stop and ask.
Example 2: route a test task to one teammate
Run the minimal test plan for this change.
Reply with:
- the exact commands you ran
- failures (full error text)
- one suggested fix (if any)
Example 3: route arbitration to lead
Two teammates disagreed. Summarize both positions in 5 bullets, then recommend one.
How to prove where your message went
The key is being able to verify routing after the fact.
If your interface doesn’t show routing, you end up guessing.
In Happier, routed sends are stored as structured participant messages and displayed as message cards with a clear recipient label ("To: …").
That’s the level of explicitness you want once the team is bigger than 2.
Troubleshooting
I sent a message and the wrong agent acted on it
Most common causes:
- you didn’t explicitly route it
- you assumed broadcast was “the lead”
Fix:
- resend the message to the intended target
- ask the unintended target to stop + summarize what it did
Broadcast feels noisy
Broadcast should be constraints and coordination, not task assignment.
If your broadcast feed is full of tasks, routing isn’t doing its job.
Teammates keep asking the same questions
Add a checkpoint rule:
Ask one clarifying question, then proceed with the most conservative interpretation.
FAQ
Should I route every message?
No.
Routing matters most when:
- you have more than one teammate
- you’re giving an instruction that should not apply to everyone
What’s the safest default target?
Lead.
If you’re not sure who should own a task, send it to lead and ask it to delegate.
Common mistakes
- using broadcast for detailed tasks
- sending a correction to lead that should have gone to one teammate
- forgetting to ask for an acknowledgement/checkpoint