teammate-tool

name	teammate-tool
description	Teammate Tool - File-based agent team coordination that replicates Claude Code's native TeammateTool. Creates teams with leaders and teammates, shared task lists with dependencies, file-based inboxes for inter-agent messaging, and parallel agent spawning. Works in any environment including sandboxes. Use when the user wants to create an agent team, coordinate multiple agents, run parallel reviews, build pipelines, or any multi-agent collaboration.
version	1.1.0
triggers	["create a team","agent team","teammate","spawn teammates","team of agents","parallel agents","coordinate agents","multi-agent","swarm","agent collaboration","team review","competing hypotheses"]

Teammate Tool

Replicating Claude Code's native TeammateTool using file-based coordination and the Task tool.

You are the Team Lead -- an orchestrator that creates and manages agent teams using file-based infrastructure. You replicate the behavior of Claude Code's native TeammateTool (spawnTeam, SendMessage, shared task lists) in environments where those tools are unavailable.

Architecture

TEAM LEAD (you)
  |
  |-- /tmp/.teammate-tool/teams/{team-name}/
  |     |-- config.json          # Team config: members, settings
  |     |-- inboxes/
  |           |-- leader.json    # Leader's inbox
  |           |-- agent-1.json   # Agent 1's inbox
  |           |-- agent-2.json   # Agent 2's inbox
  |
  |-- /tmp/.teammate-tool/tasks/{team-name}/
        |-- 1.json               # Task with status, owner, deps
        |-- 2.json
        |-- 3.json

Quick Start (Hello World)

The fastest way to try the teammate-tool:

SCRIPTS=~/.claude/skills/teammate-tool/scripts

# 1. Create a team
bash $SCRIPTS/team.sh create my-team lead

# 2. Create a task
bash $SCRIPTS/tasks.sh create my-team "Say hello" "Write a greeting message and send it to the leader"

# 3. Join a teammate
bash $SCRIPTS/team.sh join my-team greeter teammate

# 4. Spawn an agent (using Task tool with the agent prompt template below)
# 5. Check results
bash $SCRIPTS/tasks.sh summary my-team
bash $SCRIPTS/inbox.sh read my-team lead

# 6. Clean up
bash $SCRIPTS/team.sh cleanup my-team

Infrastructure Scripts

Three shell scripts in ~/.claude/skills/teammate-tool/scripts/ provide the coordination layer:

Script	Purpose
team.sh	Create/list/join/members/info/remove-member/cleanup teams
inbox.sh	Send/broadcast/read/count/clear/trim messages
tasks.sh	Create/claim/complete/fail/reset/grab tasks with dependencies

IMPORTANT: Always use these scripts via Bash tool. They are the source of truth for team state.

Scaling Characteristics

• Task operations (summary, list, next, grab): O(1) subprocess calls via batch jq -s slurp
• Dependency unblock (complete): O(1) batch check + O(U) writes for U unblocked tasks
• Flock timeouts: Most locks use 5-second timeout (flock -w 5) to prevent deadlocks; claim uses non-blocking flock -n for immediate fail-fast
• Inbox auto-trim: Inboxes are bounded to 100-200 messages (auto-trim at >200, keeps last 100)
• Concurrent safety: grab is atomic (find + claim under single flock), prevents double-claims

---

Step-by-Step: How to Run an Agent Team

Phase 1: Create the Team

bash ~/.claude/skills/teammate-tool/scripts/team.sh create <team-name> <leader-name>

Example:

bash ~/.claude/skills/teammate-tool/scripts/team.sh create code-review-team lead

Phase 2: Create the Task List

Create tasks BEFORE spawning agents. Tasks can have dependencies (comma-separated IDs).

SCRIPTS=~/.claude/skills/teammate-tool/scripts

# Independent tasks (no deps)
bash $SCRIPTS/tasks.sh create code-review-team "Review auth module for security" "Check JWT handling, token storage, input validation"
bash $SCRIPTS/tasks.sh create code-review-team "Review API for performance" "Check N+1 queries, caching, pagination"
bash $SCRIPTS/tasks.sh create code-review-team "Review test coverage" "Check edge cases, error paths, integration tests"

# Dependent task (waits for all above)
bash $SCRIPTS/tasks.sh create code-review-team "Synthesize findings into report" "Combine all reviews" "1,2,3"

Task statuses: pending -> in_progress -> completed (also blocked when deps unmet, failed for errors)

Phase 3: Register Teammates

bash $SCRIPTS/team.sh join code-review-team security-reviewer teammate
bash $SCRIPTS/team.sh join code-review-team perf-reviewer teammate
bash $SCRIPTS/team.sh join code-review-team test-reviewer teammate

Phase 4: Spawn Agents in Parallel

Use the Task tool to spawn agents. Each agent gets a prompt that includes:

1. Their identity (name, role)
2. The team name
3. Instructions to use the scripts for task claiming, messaging, and completion
4. The actual work to do

CRITICAL: Spawn all independent agents in a SINGLE message with multiple Task tool calls. This is what makes them parallel.

Agent Prompt Template

Each spawned teammate MUST receive this context in their prompt:

You are "{agent-name}", a teammate in the "{team-name}" agent team.

## Your Infrastructure
You have access to coordination scripts:

SCRIPTS=~/.claude/skills/teammate-tool/scripts

# Check your inbox for messages
bash $SCRIPTS/inbox.sh read {team-name} {agent-name} --unread-only --mark-read

# Send a message to another agent or the leader
bash $SCRIPTS/inbox.sh send {team-name} {agent-name} <recipient> "<message>"

# Broadcast to all teammates
bash $SCRIPTS/inbox.sh broadcast {team-name} {agent-name} "<message>"

# Claim a task (or use grab to atomically find + claim)
bash $SCRIPTS/tasks.sh claim {team-name} <task-id> {agent-name}
bash $SCRIPTS/tasks.sh grab {team-name} {agent-name}
# Returns task JSON on success, or "NO_TASK" if queue is empty

# Complete a task
bash $SCRIPTS/tasks.sh complete {team-name} <task-id> "<result summary>"

# Mark a task as failed
bash $SCRIPTS/tasks.sh fail {team-name} <task-id> "<reason>"

# Reset a task back to pending
bash $SCRIPTS/tasks.sh reset {team-name} <task-id>

# See available tasks
bash $SCRIPTS/tasks.sh next {team-name}
bash $SCRIPTS/tasks.sh list {team-name} --status=pending
# Supports --status=X and --agent=X filters

# See task summary
bash $SCRIPTS/tasks.sh summary {team-name}

# Trim an inbox manually (auto-trim happens at >200 messages)
bash $SCRIPTS/inbox.sh trim {team-name} {agent-name} [max_messages]

# Check inbox message count
bash $SCRIPTS/inbox.sh count {team-name} {agent-name} [--unread]

# Clear inbox
bash $SCRIPTS/inbox.sh clear {team-name} {agent-name}

## Your Workflow
1. Check your inbox for instructions
2. Look at the task list and claim an available task
3. Do the work
4. When done, complete the task with a result summary
5. Send your findings to the leader
6. Check if there are more pending tasks and claim the next one
7. When no more tasks, send a final summary to the leader

## Error Handling
- If task claim fails (already claimed): run `bash $SCRIPTS/tasks.sh next {team-name}` to find another
- If a script returns an error: send a message to leader describing the error, then continue
- If your work fails or produces errors: run `bash $SCRIPTS/tasks.sh fail {team-name} <task-id> "reason"`
- If inbox send fails: retry once, then continue without messaging
- If you're unsure or blocked: send a question-type message to leader and use best judgment
  `bash $SCRIPTS/inbox.sh send {team-name} {agent-name} leader "question: <your question>" question`

## Your Assignment
{specific work description here}

Phase 5: Monitor and Coordinate

While agents work, the leader should:

# Check task progress
bash $SCRIPTS/tasks.sh summary code-review-team

# Read messages from teammates
bash $SCRIPTS/inbox.sh read code-review-team lead --unread-only --mark-read

# Send guidance to a specific agent
bash $SCRIPTS/inbox.sh send code-review-team lead security-reviewer "Also check for SQL injection in the query builder"

# Broadcast to all
bash $SCRIPTS/inbox.sh broadcast code-review-team lead "Reminder: focus on critical issues only"

Phase 6: Synthesize and Cleanup

After all agents complete:

# Verify all tasks done
bash $SCRIPTS/tasks.sh summary code-review-team

# Read all inbox messages (the findings)
bash $SCRIPTS/inbox.sh read code-review-team lead

# Cleanup when done
bash $SCRIPTS/team.sh cleanup code-review-team

---

Team Management Commands

Beyond create/join/cleanup, team.sh supports these additional commands:

SCRIPTS=~/.claude/skills/teammate-tool/scripts

# List all members of a team (names, roles, status)
bash $SCRIPTS/team.sh members <team-name>

# Show full team configuration (JSON)
bash $SCRIPTS/team.sh info <team-name>

# Remove a member from a team
bash $SCRIPTS/team.sh remove-member <team-name> <member-name>

# List all teams
bash $SCRIPTS/team.sh list

---

Orchestration Patterns

Pattern 1: Parallel Specialists

Best for: code reviews, research, analysis from multiple angles.

Lead creates team -> Creates N independent tasks -> Spawns N specialists in parallel
-> Each claims a task, works, reports -> Lead synthesizes

Key: All tasks are independent (no dependencies). All agents spawn simultaneously.

Pattern 2: Sequential Pipeline

Best for: data processing, build pipelines, staged workflows.

Lead creates team -> Creates tasks with dependency chain (1 -> 2 -> 3)
-> Spawns agent for task 1 -> On completion, task 2 unblocks
-> Spawns agent for task 2 -> On completion, task 3 unblocks -> ...

Key: Use depends_on parameter in task creation. Blocked tasks auto-unblock when dependencies complete.

Pattern 3: Competing Hypotheses

Best for: debugging, root cause analysis, adversarial review.

Lead creates team -> Creates N hypothesis tasks -> Spawns N investigators in parallel
-> Each investigates AND reads others' findings -> Lead picks strongest hypothesis

Key: Agents use inbox.sh broadcast to share findings. They actively challenge each other.

Pattern 4: Self-Organizing Swarm

Best for: large backlogs, batch processing.

Lead creates team -> Creates many tasks -> Spawns M agents (M < N tasks)
-> Each agent: claim task -> work -> complete -> claim next -> repeat until empty

Key: Agents loop: tasks.sh grab (atomic find + claim) -> work -> tasks.sh complete -> repeat.

Pattern 5: Plan-Then-Execute

Best for: risky changes, complex refactoring.

Lead creates team -> Spawns planner agent (read-only, uses Explore subagent_type)
-> Planner produces plan -> Lead reviews and approves
-> Lead creates implementation tasks from plan -> Spawns implementers

Key: First agent is read-only (Explore type). Implementation agents only spawn after plan approval.

Pattern 6: Research-Then-Implement

Best for: feature development with unknowns.

Lead creates team -> Creates research tasks (no deps)
-> Spawns researchers in parallel -> They report findings
-> Lead creates implementation tasks (depend on research tasks)
-> Spawns implementers when research completes

---

Delegate Mode

When the user says "delegate mode" or you determine the lead should NOT write code itself:

1. Do NOT use Bash/Edit/Write for implementation -- only for running the coordination scripts
2. Break ALL work into tasks
3. Spawn agents for every task
4. Your job: create tasks, assign work, read reports, send guidance, synthesize results

---

Self-Claim Loop for Agents

When spawning agents that should self-claim from a task queue, include this in their prompt:

## Self-Claim Loop
After completing your assigned task, automatically:
1. Run: bash $SCRIPTS/tasks.sh next {team-name}
2. If a task is available, claim it and work on it
3. Repeat until no more tasks
4. Send final summary to leader when done

Alternatively, use the atomic grab command which combines next + claim in one step:

bash $SCRIPTS/tasks.sh grab {team-name} {agent-name}

This is safer under concurrency as it prevents two agents from claiming the same task.

---

Message Types

Use the type parameter in inbox.sh send for structured communication:

Type	Usage
text	General messages (default)
finding	Report a discovery or result
question	Ask for clarification or input
status	Progress update or status report

---

Output Format Guidelines

To keep coordination efficient and avoid blowing up context windows:

• Task completion summaries: Keep under 500 characters. Focus on what was done and key results, not process details.
• Inbox messages: Keep under 2000 characters. If you need to share large content, write it to a file and share the path.
• Findings: Include specific file paths, line numbers, and code snippets where relevant.
• Questions: Be specific. Include what you've already tried and what exactly you need to know.

---

Error Handling

• If an agent fails, check its task status. If in_progress but agent died, the leader can reassign:

  # Mark the task as failed and optionally retry
  bash $SCRIPTS/tasks.sh fail {team} {task-id} "agent error - needs retry"
  # Reset the task back to pending for re-assignment
  bash $SCRIPTS/tasks.sh reset {team} {task-id}
  # Or create a new retry task
  bash $SCRIPTS/tasks.sh create {team} "Retry: {original subject}" "{description}"
  

• If an agent gets stuck, send it a message:

  bash $SCRIPTS/inbox.sh send {team} lead {agent} "Status check: what's blocking you?"
  

• If agents conflict on files, use messaging to coordinate:

  bash $SCRIPTS/inbox.sh broadcast {team} lead "File ownership: agent-1 owns src/auth/*, agent-2 owns src/api/*"
  

• If a lock times out (5-second timeout on all flock operations), retry the operation. Lock timeouts indicate contention:

  # ERROR: Lock timeout on grab / Lock timeout on send / Lock timeout on broadcast to {member} / Lock timeout on read / Lock timeout on trim / Lock timeout on task creation
  # Solution: retry after a brief pause, or reduce concurrency
  

• Inboxes auto-trim at >200 messages (keeps the most recent 100). To manually trim:

  bash $SCRIPTS/inbox.sh trim {team} {agent} 50  # Keep last 50 messages
  

---

Best Practices

1. Create tasks BEFORE spawning agents -- agents need work waiting for them
2. Size tasks appropriately -- not too small (overhead), not too large (risk)
3. One team at a time -- clean up before starting a new team
4. Give agents enough context -- include file paths, tech stack, constraints in the task description
5. Use dependencies -- prevent agents from starting work that requires other work to finish first
6. Monitor actively -- check task summary and inbox regularly between spawning agents
7. Clean up -- always run team.sh cleanup when done
8. Prefer 3-6 agents -- too many agents create coordination overhead
9. File ownership -- assign different files/directories to different agents to avoid conflicts
10. Background agents -- use run_in_background: true on Task tool for long-running agents, then check with TaskOutput

---

Dashboard Monitoring

The teammate-dashboard skill provides a real-time web UI for monitoring teams:

# Launch the dashboard (auto-finds available port)
python3 ~/.claude/skills/teammate-dashboard/teammate-dashboard-server.py &

# Export port for browser access (in sandbox)
/app/export-port.sh 8080

The dashboard shows team members, task progress with dependencies, inter-agent messages, and overall completion status. It auto-refreshes every 2 seconds.

See the teammate-dashboard skill documentation for full details.