Agent Coordination

Agent coordination enables multiple Claude instances to work together on complex projects. Agents can create tasks, claim work, communicate, and coordinate their efforts.

Overview

When you have multiple Claude sessions working on a project, agent coordination helps them:

• Discover each other - See who else is working
• Distribute work - Create and claim tasks
• Communicate - Send messages between agents
• Coordinate - Avoid duplicate work and conflicts

Heartbeat

Keep your session active and discover other agents:

"send agent heartbeat"

The heartbeat:

• Marks your session as active
• Returns information about other active agents
• Should be sent periodically during long work sessions

{
  "session_id": "abc123",
  "status": "active",
  "other_agents": [
    {
      "id": "def456",
      "name": "Agent 2",
      "role": "testing",
      "last_heartbeat": "2024-01-15T10:30:00Z"
    }
  ]
}

Task Management

Creating Tasks

Create tasks for yourself or other agents:

"create agent task: Review PR #123 with priority high and tag 'code-review'"

{
  "title": "Review PR #123",
  "description": "Review the pull request for the new feature",
  "priority": "high",
  "tags": ["code-review"],
  "estimated_effort": "small",
  "required_skills": ["typescript", "testing"]
}

Priority Levels

• urgent - Needs immediate attention
• high - Important, do soon
• medium - Normal priority
• low - Do when convenient

Effort Estimates

• quick - Few minutes
• small - Under an hour
• medium - A few hours
• large - Multiple sessions

Listing Tasks

"list open agent tasks"
"list tasks assigned to me"
"find tasks matching my capabilities"

Claiming Tasks

"claim agent task task-abc123"

Once claimed, the task is assigned to your session and won't be picked up by others.

Updating Tasks

"update agent task task-abc123 status in_progress"
"mark agent task task-abc123 as completed"

Task statuses:

• open - Available to claim
• claimed - Assigned but not started
• in_progress - Currently being worked on
• completed - Done
• cancelled - No longer needed

Messaging

Sending Messages

Send directed messages to specific agents:

"send agent message to session def456: Can you handle the database migration?"

Or broadcast to all agents:

"broadcast agent message: Starting deployment, please hold off on changes"

Message Types (Performatives)

FIPA-inspired message types:

"send REQUEST message to agent def456: Can you review the API changes?"
"send INFORM message broadcast: Tests are now passing"

Reading Messages

"get my agent messages"
"get unread agent messages"

Conversations

Link messages to conversations:

"send agent message to def456 in conversation 'pr-review': LGTM, approved"

Workload Distribution

View how work is distributed:

"show agent workload"

{
  "agents": [
    {
      "id": "abc123",
      "tasks_claimed": 2,
      "tasks_in_progress": 1,
      "capacity": 3
    },
    {
      "id": "def456",
      "tasks_claimed": 1,
      "tasks_in_progress": 0,
      "capacity": 3
    }
  ],
  "open_tasks": 5,
  "total_in_progress": 1
}

Activity Stream

Posting Events

Share significant events:

"post agent event: Completed database migration, severity info"
"post agent event: Build failing on main branch, severity warning"

Severity levels:

• info - General updates
• warning - Potential issues
• error - Problems requiring attention

Reading Events

"get recent agent events"
"get events from other agents"

Example Workflow

Multi-Agent Project Setup

# Agent 1: Project Lead
"create agent task: Set up test infrastructure, priority high, effort medium"
"create agent task: Implement user authentication, priority high, effort large"
"create agent task: Write API documentation, priority medium, effort small"

# Agent 2: Backend Developer
"find tasks matching capabilities typescript, databases"
"claim agent task task-auth-123"
"update agent task task-auth-123 status in_progress"
"send INFORM message broadcast: Starting auth implementation"

# Agent 3: Technical Writer
"list open agent tasks with tag documentation"
"claim agent task task-docs-456"

Coordinated Feature Development

# Agent 1: Working on API
"send REQUEST message to agent-2: Need the database schema before I can finish the API"

# Agent 2: Database work
"send INFORM message to agent-1: Schema is ready, see migrations/004_users.sql"

# Agent 1: Continues
"send REPORT message to agent-2: API endpoints complete, ready for integration testing"

Best Practices

Task Creation

• Use clear, specific titles
• Include enough description for context
• Set realistic effort estimates
• Use consistent tags

Communication

• Use appropriate performatives
• Keep messages concise
• Reference tasks when relevant
• Broadcast important status changes

Coordination

• Send heartbeats regularly
• Claim tasks before starting work
• Update task status as you progress
• Mark tasks complete when done

Agent Tools Reference