Multi-Agent Coordination

When multiple agents work on the same codebase, they need to coordinate. Synapses provides messaging, work claims, and optional AI-powered orchestration to prevent conflicts and enable collaboration.

Work Ledger (Ambient Coordination)

Synapses uses a Work Ledger for multi-agent coordination. Instead of explicit message-passing (the old send_message/get_messages tools have been removed), agents coordinate ambiently through the shared task and session state.

When an agent calls session_init, it automatically sees:

• What other agents are working on (active tasks and claimed work)
• Recent changes from other agents (git state, modified files)
• Any conflicts or overlapping work areas

This ambient awareness replaces explicit messaging — agents naturally avoid conflicts by observing the shared ledger state.

Work Claims via Tasks

The task system doubles as a work-claiming mechanism. When an agent starts a task, other agents see it as claimed:

// Agent A claims the task
{
  "tool": "tasks",
  "arguments": {
    "action": "update",
    "task_id": "refactor-auth",
    "status": "in_progress",
    "claimed_by": "agent-a"
  }
}

// Agent B checks tasks and sees it is claimed
{
  "tool": "tasks",
  "arguments": {
    "action": "pending"
  }
}
// Returns: refactor-auth (in_progress, claimed by agent-a)
// Agent B picks a different task

This prevents two agents from working on the same thing simultaneously.

Claim Conflicts

If two agents try to claim the same task, the first claim wins. The second agent receives a conflict response:

{
  "conflict": true,
  "claimed_by": "agent-a",
  "claimed_at": "2026-03-28T10:30:00Z"
}

Brain Tier 3: Orchestrator

With Brain Tier 3 enabled, Synapses adds an AI orchestrator that actively manages multi-agent coordination.

What the Orchestrator Does

• Conflict resolution — detects when two agents are modifying related files and mediates
• Work distribution — suggests optimal task assignment based on agent capabilities and current workload
• Dependency tracking — alerts agents when a dependency they rely on is being modified by another agent
• Global awareness — maintains a unified view of all agent activities across the codebase

Enabling the Orchestrator

{
  "brain": {
    "enabled": true,
    "model": "llama3",
    "max_tier": 3
  }
}

Orchestrator Awareness

The orchestrator surfaces coordination insights through the Work Ledger. When agents call session_init, orchestrator warnings (such as overlapping file modifications) appear automatically in the response. No explicit message polling is needed.

Example: Two-Agent Workflow

Agent A (backend):
  1. session_init(agent_id="agent-backend")
  2. tasks(action="pending") → sees "add-role-field", "update-auth-flow"
  3. tasks(action="update", task_id="add-role-field", status="in_progress", claimed_by="agent-backend")
  4. [implements the change]
  5. tasks(action="update", task_id="add-role-field", status="done",
     outcome="Added 'role' field to /users response. Type: string, values: admin|user|guest")

Agent B (frontend):
  1. session_init(agent_id="agent-frontend")
     → Work Ledger shows "add-role-field" claimed by agent-backend, sees recent changes
  2. tasks(action="update", task_id="update-auth-flow", status="in_progress", claimed_by="agent-frontend")
  3. [updates frontend to use the new role field based on ledger context]
  4. tasks(action="update", task_id="update-auth-flow", status="done")

Best Practices

• Claim tasks before starting work. This is the primary mechanism for preventing conflicts.
• Call session_init between tasks. The Work Ledger updates automatically, giving you awareness of other agents’ activity.
• Record outcomes in task updates. Other agents see task outcomes through the shared ledger, replacing the need for explicit messages.
• Let the orchestrator mediate conflicts. If using Tier 3, defer to orchestrator guidance rather than trying to resolve file conflicts manually.