Akshay Parkhi's Weblog

How Claude Team Agents ACTUALLY Connect — No Fluff

7th March 2026

The Brutal Truth

Agents are separate processes. They don’t share memory. They don’t call each other’s functions. They communicate through files on disk and CLI commands that Claude Code provides as tools.

That’s it. Files and tools. Nothing magical.

---

Let’s Trace EXACTLY What Happens

Step 0: You Have ONE Claude Code Session

You type a prompt. Claude Code (the lead) has access to special tools (think of them as bash commands) that it can call.

Step 1: Lead SPAWNS a Teammate

When you say “create a team with 3 teammates”, Claude Code calls a tool like spawn_teammate("analyst", "You are an analyst..."). A NEW Claude Code process starts (like opening another terminal and running claude). This new process gets its own context window (fresh conversation), the spawn prompt is injected as the first message, and the new process is registered in a config file:

~/.claude/teams/my-team/config.json
{
  "members": [
    { "name": "lead",    "agentId": "abc123", "type": "lead" },
    { "name": "analyst", "agentId": "def456", "type": "teammate" }
  ]
}

The teammate is literally another claude process running on your machine:

Process 1: claude (lead)         <- your original session
Process 2: claude (analyst)      <- spawned by lead
Process 3: claude (architect)    <- spawned by lead
Process 4: claude (developer)    <- spawned by lead

Each process runs independently. They don’t share memory or conversation history.

Step 2: How They ACTUALLY Send Messages

When the analyst wants to tell the architect something, it calls a tool:

Tool: send_message
Arguments:
  to: "architect"
  message: "Requirements are done. Key points: 1) Must support .ts files..."

What happens under the hood:

1. The message is written to a mailbox file on disk
2. Claude Code’s runtime detects a new message for “architect”
3. The message is injected into the architect’s conversation as a system/user message
4. The architect sees it and can respond

~/.claude/teams/my-team/mailbox/
+-- architect_inbox/
|   +-- msg_001.json    <- { from: "analyst", body: "Requirements are done..." }
+-- developer_inbox/
|   +-- (empty)
+-- analyst_inbox/
    +-- (empty)

It’s like email. One process writes a file, the other process reads it. The Claude Code runtime handles the plumbing automatically.

Step 3: How the Shared Task List Works

The task list is also just files on disk:

~/.claude/tasks/my-team/
+-- task_001.json
+-- task_002.json
+-- task_003.json

Each task file looks something like:

{
  "id": "task_001",
  "title": "Write requirements",
  "assignee": "analyst",
  "status": "in_progress",
  "description": "Gather and document requirements..."
}

{
  "id": "task_002",
  "title": "Design architecture",
  "assignee": "architect",
  "status": "pending",
  "dependsOn": ["task_001"],
  "description": "Create system design..."
}

When the analyst finishes and marks task_001 as “completed”:

1. The task file is updated on disk
2. The runtime checks: “Does any pending task depend on task_001?”
3. Yes — task_002 depends on it. task_002 is now unblocked.
4. The architect gets notified: “Your task is ready”

File locking prevents two teammates from claiming the same task.

---

SUBAGENTS vs TEAM AGENTS — The REAL Difference

Subagents: Function Calls Inside One Process

Main Claude Session (Process 1)

You: "Research these 3 libraries"

Claude calls tool:
  +-- Subagent A: researches React
  +-- Subagent B: researches Vue
  +-- Subagent C: researches Svelte

Each subagent runs, does work, and returns
a TEXT RESULT back to the main session.

Main session receives:
  Result A: "React has..."
  Result B: "Vue has..."
  Result C: "Svelte has..."

Main session synthesizes the results.

Key points about subagents:

• They run INSIDE the main session’s process
• They get their own context window (so they don’t eat the main context)
• They can ONLY send results BACK to the main session
• Subagent A CANNOT talk to Subagent B. Ever.

Main --spawn--> Subagent A --result--> Main
Main --spawn--> Subagent B --result--> Main
Main --spawn--> Subagent C --result--> Main

Subagent A --X--> Subagent B    <- IMPOSSIBLE

Team Agents: Separate Processes That Message Each Other

Process 1: LEAD        Process 2: ANALYST     Process 3: ARCHITECT

Lead spawns --------> Analyst
Lead spawns ----------------------------> Architect

                       Analyst writes msg -> Architect reads msg
                       Architect replies --> Analyst reads reply

All share:
  +-- ~/.claude/teams/my-team/    (config, mailbox)
  +-- ~/.claude/tasks/my-team/    (task list)
  +-- Your project files          (normal file I/O)

Key points about team agents:

• Each agent is a SEPARATE claude process
• They communicate through FILES ON DISK (mailbox)
• Agent A CAN talk to Agent B directly
• They share a task list (also files on disk)
• The lead coordinates but doesn’t relay all messages
• You can talk to any teammate directly (Shift+Down)

---

Side-by-Side Comparison with a Real Example

Scenario: “Review this PR for security, performance, and tests”

With Subagents:

You --> Main Claude Session

  +-- spawn subagent("review security")  --> returns "SQL injection on line 23"
  +-- spawn subagent("review perf")      --> returns "N+1 query on line 45"
  +-- spawn subagent("review tests")     --> returns "Missing edge case tests"

  Main session gets 3 text results
  Main session writes the combined review

  WARNING: Security reviewer can't ask perf reviewer:
     "Is that N+1 query also a security risk?"
     They can't talk to each other.

With Team Agents:

You --> Lead (Process 1)
  +-- spawns Security Reviewer (Process 2)
  +-- spawns Perf Reviewer (Process 3)
  +-- spawns Test Reviewer (Process 4)

Security Reviewer --message--> Perf Reviewer:
  "That N+1 query - is it user-input driven? Could be a DoS vector."

Perf Reviewer --message--> Security Reviewer:
  "Yes, the query param comes from user input. Confirm it's a DoS risk."

Test Reviewer --message--> Security Reviewer:
  "I see no test for SQL injection on line 23. Should I flag it?"

Security Reviewer --message--> Test Reviewer:
  "Yes. Add payload to test with: ' OR 1=1 --"

All three --idle notify--> Lead
Lead synthesizes the combined review with cross-cutting findings

The team agents discovered a DoS risk that neither would have found alone. That’s the real value — they CHALLENGE and BUILD ON each other’s findings.

---

The Connection Mechanism Summarized

Mechanism	Tool	How It Works
Spawning	spawn_teammate(name, prompt)	New claude process starts, registered in config.json
Messaging	send_message(to, body)	Write to mailbox file on disk, runtime injects into recipient’s conversation
Broadcasting	broadcast(body)	Write to ALL mailboxes
Task Coordination	update_task(id, status)	Update task JSON file, dependent tasks auto-unblock
Shared Files	Normal file I/O	Agent A writes design/api-spec.md, Agent B reads it
Idle Notification	Automatic	Lead gets notified when teammate stops working (no polling)

---

What Subagents CANNOT Do (That Team Agents Can)

Capability	Subagents	Team Agents
Talk to each other	NO	YES
Work in parallel (truly)	YES (but return to main)	YES
You interact with them directly	NO (only main session)	YES
Persist after returning result	NO (they die)	YES (stay alive)
Share a task list	NO	YES
Self-claim work	NO	YES

What Team Agents CANNOT Do (That Subagents Can)

Capability	Subagents	Team Agents
Cheap (low token cost)	YES	NO (each is full session)
Simple to manage	YES	NO (coordination overhead)
Survive session resume	YES	NO
Nested (agents spawn agents)	YES	NO

Analogy

Subagents = You hire 3 contractors. You give each one a task. They do it and email you the result. They never meet each other.

Team agents = You hire 3 people into a team. They sit in the same (virtual) office. They have a shared to-do board (Trello/Jira). They can walk over to each other’s desk and talk. You’re the manager who checks in on them.

The “desk” is a Claude Code process. The “walking over to talk” is the send_message tool writing to a mailbox file. The “shared to-do board” is task JSON files on disk. The “office” is your machine running multiple claude processes.

---

Agent Team Lifecycle Management

The Full Lifecycle

1. ENABLE        Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
       |
2. CREATE        Lead creates team, spawns teammates
       |
3. ASSIGN        Lead creates tasks, assigns or teammates self-claim
       |
4. WORK          Teammates work in parallel, communicate
       |
5. MONITOR       You interact with teammates, steer work
       |
6. COMPLETE      Tasks finish, lead synthesizes results
       |
7. SHUTDOWN      Teammates shut down gracefully
       |
8. CLEANUP       Lead removes team resources

Phase 1: Enable

Agent teams are disabled by default. Enable them:

# Environment variable
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Or in settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Phase 2: Create the Team

Tell Claude to create a team. You describe: team name (identifies the team in ~/.claude/teams/), number of teammates (start with 3-5), roles and prompts (what each teammate should do), and task dependencies (what must finish before what starts).

What happens behind the scenes:

1. Claude creates ~/.claude/teams/my-team/config.json
2. Spawns each teammate as an independent Claude Code instance
3. Each teammate loads CLAUDE.md and receives their spawn prompt
4. Shared task list is created at ~/.claude/tasks/my-team/

Phase 3: Assign Tasks

The lead breaks work into tasks. Each task has:

• Title: what needs to be done
• Description: details and acceptance criteria
• Assignee: which teammate (or unassigned for self-claim)
• Dependencies: which tasks must complete first
• Status: pending → in progress → completed

Phase 4: Work Phase

Teammates work independently and in parallel. Each has their own context window (no shared memory). They read/write files in the project, message each other to coordinate, and claim tasks from the shared task list.

Phase 5: Monitor and Steer

You can interact with the team at any time:

• Shift+Down — cycle through teammates
• Type — send a message to the current teammate
• Enter — view a teammate’s session
• Escape — interrupt a teammate’s turn
• Ctrl+T — toggle the task list

Common interventions:

• “Wait for your teammates to finish before proceeding”
• “Redirect the architect to focus on the data layer”
• “The developer’s approach won’t scale, tell them to use streams instead”

Phase 6-8: Completion, Shutdown, Cleanup

When tasks complete, dependent tasks automatically unblock and the lead receives idle notifications. Ask teammates to shut down gracefully — they finish their current operation before stopping. Always use the lead to clean up: it removes team config from ~/.claude/teams/ and the task list from ~/.claude/tasks/.

Important: Cleanup fails if teammates are still running. Shut them down first. Never let a teammate run cleanup — only the lead should do this.

---

Maintaining Teams Over Time

Limitation	Details
Session Resumption	Agent teams do NOT survive session resumption. If you use /resume or /rewind, in-process teammates are lost. Fix: tell the lead to spawn new teammates.
One Team at a Time	A lead can only manage one team. To start a new team: shut down all teammates, clean up, then create the new team.
No Nested Teams	Teammates cannot spawn their own teams. Only the lead manages the team.
Permissions	All teammates start with the lead’s permission settings. You can change individual teammate modes after spawning, but not at spawn time.

---

Quality Gates with Hooks

TeammateIdle Hook: Runs when a teammate is about to go idle. Return exit code 2 to send feedback and keep them working. Use case: “Don’t go idle until all your files pass linting.”

TaskCompleted Hook: Runs when a task is marked complete. Return exit code 2 to prevent completion and send feedback. Use case: “Don’t mark tests as complete if any test fails.”

---

Cost Management

Token usage scales with team size: 1 teammate = ~1x tokens, 3 teammates = ~3x tokens, 5 teammates = ~5x tokens.

Tips to control costs:

• Use fewer teammates for simple tasks
• Use Sonnet (cheaper) for teammates doing routine work
• Shut down teammates as soon as their work is done
• Avoid unnecessary broadcast messages
• Keep spawn prompts focused and concise

---

Common Commands Reference

Action	What to tell Claude
Create team	“Create an agent team called X with N teammates...”
Check status	“What’s the status of all tasks?”
Message teammate	“Tell the architect to focus on the API layer”
Reassign task	“Reassign the testing task to the developer”
Shut down one	“Ask the analyst to shut down”
Shut down all	“Shut down all teammates”
Clean up	“Clean up the team”
Specify model	“Use Sonnet for each teammate”

---

Step-by-Step Demo: Watch Agents Connect

Step 1: Enable and start

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
cd /your/project/directory
claude

Step 2: Paste this minimal example

Create an agent team called "demo" with 2 teammates:

1. "alice" - Write a haiku about coding to examples/alice-haiku.txt
2. "bob" - Write a haiku about debugging to examples/bob-haiku.txt

After alice writes her haiku, have her send it to bob.
After bob receives alice's haiku, have bob write a response haiku
that references alice's haiku. Save it to examples/bob-response.txt.

What you’ll SEE happen (in order):

STEP 1: Lead creates team
  Lead calls: create_team("demo")
  Creates ~/.claude/teams/demo/config.json

STEP 2: Lead spawns alice
  Lead calls: spawn_teammate("alice", "Write a haiku about coding...")
  New claude process starts (PID 12345)

STEP 3: Lead spawns bob
  Lead calls: spawn_teammate("bob", "Write a haiku about debugging...")
  New claude process starts (PID 12346)

STEP 4: alice works
  alice (Process 12345) writes: examples/alice-haiku.txt
    "Semicolons fall
     like autumn leaves in the wind
     the code compiles clean"

STEP 5: alice messages bob
  alice calls: send_message(to="bob", message="Here's my haiku: ...")
  Message written to bob's mailbox file on disk
  Claude Code runtime detects new message
  Message injected into bob's conversation

STEP 6: bob receives and responds
  bob (Process 12346) sees the message in his conversation
  bob writes: examples/bob-response.txt
    "Your leaves now have bugs
     stack traces fall like the rain
     printf saves the day"

STEP 7: Lead synthesizes
  Lead sees both are done, synthesizes.

STEP 8: You clean up
  You: "Shut down all teammates and clean up the team"
  alice process exits, bob process exits
  Team files deleted from ~/.claude/teams/demo/

Step 3: Interact with teammates WHILE they work

Press Shift+Down to jump to alice’s session. Type: “Also write a limerick” — alice will see your message and act on it. Press Shift+Down again to jump to bob’s session. Type: “Make your haiku funny” — bob will adjust. Press Shift+Down again to return to the lead.

Step 4: Watch the files appear

# In another terminal, watch the output
watch -n 1 'ls -la examples/'

You’ll see files appear as each agent writes them.

---

The Physical Reality on Your Machine

While the team runs, here’s what exists:

# Running processes
ps aux | grep claude
  claude (lead)      PID 12344
  claude (alice)     PID 12345
  claude (bob)       PID 12346

# Team config
cat ~/.claude/teams/demo/config.json
  {"members": [
      {"name":"lead", "agentId":"abc", "type":"lead"},
      {"name":"alice","agentId":"def", "type":"teammate"},
      {"name":"bob",  "agentId":"ghi", "type":"teammate"}
  ]}

# Task files
ls ~/.claude/tasks/demo/
  task_001.json   (alice's task)
  task_002.json   (bob's task)

# Your project files (written by agents)
ls examples/
  alice-haiku.txt
  bob-haiku.txt
  bob-response.txt

That’s ALL it is. Processes + JSON files + your project files. No servers. No databases. No network calls between agents. Just processes reading and writing files on your local disk.