← 20.520.7 →
1845 words No Slides

Video 20.6: Communicating with Teammates

Course: Claude Code - Parallel Agent Development Section: S20 - Agent Teams Video Length: 4 minutes Presenter: Daniel Treasure

Opening Hook

A shared task list keeps the team aligned on what needs doing. But real collaboration happens through conversation. Let's explore how to send direct messages, relay information, and keep communication focused and productive.

Key Talking Points

What to say:

Three Ways to Communicate in a Team

  1. Through the Task List
  2. Implicit communication: task title, description, dependencies tell the story
  3. Low-bandwidth but clear
  4. Example: "Design the API" task assigned to architect means they know what to do

  5. Good for: clear, unambiguous work

  6. Direct Teammate-to-Teammate Messages

  7. One teammate sends a message to another teammate
  8. Lead can facilitate but doesn't have to be in the middle
  9. Use for clarifications, updates, and collaboration

  10. Example: API dev to frontend dev: "The endpoint is at /api/users with these fields"

  11. Lead Relaying and Coordinating

  12. Lead receives status from one teammate, shares with another
  13. Lead is the hub in a hub-and-spoke model
  14. Use when there's sensitive info or strategic decisions needed
  15. Example: Lead learns database design is done, tells frontend it's safe to start

In-Process Display Mode Communication - All teammates in one terminal window (default) - Navigate between teammates with Shift+Up and Shift+Down - When you're "in" a teammate's context, you see their work and can message them - Type to send a message to the currently selected teammate - Message appears in their context; they respond - Simple but requires manual navigation

Sending Messages (In-Process Mode) - Press Shift+Down to navigate to a specific teammate - See their context and recent work - Type your message: "How's the API coming along?" - The message is delivered; they see it and can respond - Your next keystroke is part of the ongoing conversation or switches context

Teammate-to-Teammate Messaging - Teammates can message each other directly - Example: Frontend dev asks API dev, "Are the validation endpoints ready?" - No lead involvement needed for peer communication - Keeps conversations focused and reduces bottlenecks - Lead can view the conversation history in the task board or context

@Mentions for Directed Communication - Use @teammate_name to direct a message - Example: "Hey @api_dev, is the auth endpoint done?" - Highlights the message for that specific teammate - Good for: urgent requests, important clarifications - Works in both lead-to-teammate and teammate-to-teammate contexts

Message Best Practices - Be specific: "What's the status?" vs "The /users endpoint needs to handle array requests. Can you add that?" - Include context: reference the task ID if relevant - Assume async: don't expect instant responses - Keep it short: teammates are focused on work, not reading essays - Use task descriptions for detailed specs, messages for clarifications

Shared Context and Visibility - Each teammate has their own context window (independent work) - Messages are stored and visible to relevant parties - Lead can view all messages (hub perspective) - Teammates see messages directed at them and their peer conversations - Shared task list acts as the "memory" of what was decided

Communication Patterns

  1. Blocking Pattern (used when team is stuck)
  2. Lead: "Hey @qa_dev, the API team finished. Can you test?"
  3. QA: "Starting tests now"
  4. QA: "Found 3 bugs. Logged them in the task board"
  5. Lead: "Good catch. @api_dev, can you fix these?"

  6. API: "Fixing now"

  7. Coordination Pattern (parallel work)

  8. Lead: "Frontend and API can work in parallel. API design is done."
  9. Frontend: "@api_dev, what's the response format for /products?"
  10. API: "See the OpenAPI spec in the design doc. GET returns array of objects with id, name, price"

  11. Frontend: "Got it, starting component"

  12. Status Check Pattern (lead maintains visibility)

  13. Lead: "Quick status everyone"
  14. API: "Design done, moving to implementation"
  15. Frontend: "Waiting on API design, ready to start"
  16. QA: "Ready when you are"
  17. Lead: "Got it. Unblocking frontend now"

When to Message vs When to Use Tasks - Use Tasks: Planning, assignments, dependencies, formal handoffs - Use Messages: Clarifications, status updates, informal coordination, problem-solving - Both together: strong team communication

What to show on screen:

  • Terminal with multiple teammates active
  • Navigate between teammates using Shift+Up/Down
  • Send a direct message from lead to a teammate
  • Show the teammate responding
  • Demonstrate @mentions in a message
  • Show teammates messaging each other (without lead involvement)
  • Display message history in context
  • Show the lead checking status across the team
  • Demonstrate relay pattern: lead communicates between specialists

Demo Plan

0:00-0:45 - Set Up Multiple Teammates - Show a team with 3-4 teammates already working on tasks - Narrate: "We have a team working in parallel. How do they stay in sync?" - Show the current teammate context (should be the lead's initially) - Point out the context indicator showing who is "active" in the terminal

0:45-1:30 - Navigate Between Teammates - Press Shift+Down to move to the next teammate - Show the view change: now you're "in" the first teammate's context - Narrate: "Now I'm looking at the API developer's context. I can see what they're working on" - Show their active tasks and recent work - Press Shift+Down again to move to another teammate - Show context switching is smooth and immediate

1:30-2:15 - Send a Direct Message - While in a teammate's context, type a message: "How's the API design coming along?" - Show the message appear in their context - Narrate: "I just sent a message to the API developer. They see it and can respond" - Show the teammate's response: "Design is done, OpenAPI spec is ready" - Have a brief back-and-forth: "Great, the frontend team can start now"

2:15-2:50 - Demonstrate @Mentions and Relay - Navigate to the frontend teammate's context - Send a message: "@api_dev has the OpenAPI spec ready. Check the design doc when you're ready" - Narrate: "I'm relaying information between specialists. This is the lead's job—keeping everyone connected" - Show the frontend teammate acknowledge and start working on components - Demonstrate the @mention highlighting the message for the API dev

2:50-3:30 - Show Peer Communication - Optionally show two teammates messaging each other directly (if the UI supports it) - Or narrate: "Teammates can also message each other directly. For example, when the frontend needs clarification on the API, they ask the API dev directly instead of going through me" - This reduces bottlenecks and keeps communication natural - Show a quick example if possible; if not, explain it clearly

3:30-4:00 - Lead-out - Confirm that communication is flexible: tasks organize work, messages coordinate it - Next video is about display modes: in-process vs tmux split panes - Tease: "If you want to see all teammates at once, there's a better way than navigating"

Code Examples & Commands

# In Claude Code terminal:
Shift+Down      # Move to next teammate
Shift+Up        # Move to previous teammate

Sending a Message to a Teammate

# When you're in a teammate's context, just type:
> How's the API design coming along?

# The message is delivered to that teammate.
# They see it in their context and can respond.

Using @Mentions

# Direct a message to a specific teammate:
> @frontend_dev, the API endpoints are ready. You can start on components.

# Or from a teammate context:
> @api_dev, are we using REST or GraphQL? I need to align my schema.

Status Check from Lead

# Check in with the whole team:
> Hey everyone, quick status update

# Then navigate to each teammate and ask:
> What's blocking you right now?
> When will you be done with that task?
> Do you need anything from anyone else?

Relaying Information

# To API dev:
> The database schema is done. You can start API design.

# To frontend dev:
> The API is ready. The endpoints are /api/users, /api/products, /api/orders.
> Check the OpenAPI spec in the shared design doc.

Task-Based Context

# Messages often reference tasks:
> @qa_dev, I've assigned you the "smoke test" task. It's ready to start.

# Or:
> The "API implementation" task is unblocked now. You can start whenever.

Gotchas & Tips

Gotchas: - In in-process mode, you can only message the teammate you're currently "in" (selected with Shift) - Messages don't persist in a permanent chat log; they're context-based (consider the task description as permanent record) - If a teammate is idle or has moved to a different context, your message might not be seen immediately - Very long messages get truncated in some displays; keep messages concise - Shift+Up/Down might be slow if teammates are doing heavy computation; wait for context switch to complete

Tips: - Keep messages short and actionable. Detailed specs go in task descriptions. - Use @mentions for important information that shouldn't be missed - Check task board before messaging; the answer might already be there - Establish a rhythm: lead checks status at regular intervals (e.g., every 15 minutes) - Use messages for "soft" requests; tasks are for "hard" assignments - When relaying between teammates, be clear who said what: "The API team says the endpoint will be ready by X" - If a message is important, also add it to the task description as backup

Lead-out

Now you know how to coordinate through tasks and messages. But in-process navigation gets tedious with many teammates. In the next video, we'll explore display modes—how to see all teammates at once using tmux split panes, and alternative setups that let your entire team work in parallel on the same screen.

Reference URLs

  • Claude Code Terminal Shortcuts: https://www.anthropic.com/claude-code/docs/keyboard-shortcuts
  • Team Communication Patterns: https://www.anthropic.com/research/agent-communication
  • Asynchronous Coordination in Distributed Systems: https://www.anthropic.com/research/distributed-coordination

Prep Reading

  • Review common team communication patterns from agile/lean project management
  • Understand the concept of "hub-and-spoke" communication topology
  • Think about how bottlenecks form in communication (why peer messaging matters)
  • Familiarize yourself with Shift+Up/Down navigation if your terminal supports it

Notes for Daniel

This video is about feeling natural and human. The messages should sound like real work conversation, not robotic status reports. Show the lead navigating between teammates with intention—not randomly hopping, but checking in on specific people with specific questions. The @mention feature is powerful; use it to show how information flows. Emphasize that teammates messaging each other directly (without lead involvement) reduces bottlenecks and builds team autonomy. Keep the demo conversational, not transactional. The pacing should feel like a real work session: context switch, quick question, context switch, relay info, etc.

Risk: message delivery might not be instant; if it appears slow, talk through what's happening. If Shift+Up/Down doesn't work in your terminal, demonstrate with a pre-recorded clip or explain the concept clearly and show in text form.