Multi-Agent Coordination

Coordinate multiple coding agents around one shared project reality. Snipara keeps the Project Brain; Companion acts as the engineering lead; Claude, Codex, Cursor, GPT, or custom agents execute scoped work and return receipts, evidence, and outcomes.

Project Brain First

Agents do not collaborate because they chat. They collaborate because they share the same project reality: decisions, active work, ownership, impact, proof, and outcomes that survive across sessions and tools.

This makes orchestration a consequence of Project Intelligence. Swarms, claims, shared state, and hierarchical tasks are the coordination mechanics; the Project Brain is the point of truth that keeps those mechanics from becoming another message thread.

What Snipara prevents

How it differs

The Companion Engineering Lead Plan is intentionally advisory and fail-closed today. It can recommend supervised work packages, worker roles, scoped contracts, proof gates, fallback, replan triggers, and candidate Brain updates, but delegated execution still needs explicit approval, handoff receipts, and outcome evidence.

For a public proof example, see the Engineering Lead Plan replay: it shows recommended workers, proof gates, fallback, receipts, outcomes, and candidate Project Brain updates without claiming autonomous execution.

Canonical MCP Shape

The examples below use canonical snipara_* tool names and snake_case arguments. Legacy snipara_task_* queue aliases are not the canonical surface for new workflows; use snipara_htask_* for hierarchical work.

Overview

Multi-Agent Coordination gives the shared project reality executable coordination primitives:

• Swarms - Groups of agents working toward a shared goal
• Claim Leases - Prevent conflicts and recover when an agent drops
• Shared State - Versioned key-value state across agents
• Htasks - Hierarchical tasks with owners, evidence, policy, and audit
• Presence and Capability Discovery - See who is online, stale, or suited for work
• Event Timelines - Broadcast events plus persisted audit rows

Swarms

A swarm is a coordinated group of agents working together. Each swarm has an ID, shared state, membership and capability labels, and can coordinate through claims, htasks, and events.

Creating a Swarm

const swarm = await snipara_swarm_create({

  name: "auth-refactor",

  description: "Migrate authentication from sessions to JWT",

  max_agents: 5,

  reuse_existing: true

})

Joining a Swarm

Agents join with a stable agent_id. Use capabilities to make routing and operator review more useful.

await snipara_swarm_join({

  swarm_id: "swarm_abc123",

  agent_id: "worker-api",

  role: "worker",

  capabilities: ["backend", "tests"]

})

Swarm Roles

Listing Swarm Members

Inspect who is in the swarm, their role, advertised capabilities, and heartbeat health.

const members = await snipara_swarm_members({

  swarm_id: "swarm_abc123"

})

Leaving or Removing an Agent

Remove an agent when work is done or when a crashed worker needs cleanup. Leaving releases held claims and unassigns that agent's queued work.

await snipara_swarm_leave({

  swarm_id: "swarm_abc123",

  agent_id: "worker-api"

})

Resource Claims

Claims prevent multiple agents from modifying the same resource simultaneously. Use exclusive claims for surfaces where overlap should block other agents, such as migrations, deploy scripts, auth, billing, and schema work.

Claiming a Resource

const claim = await snipara_claim({

  swarm_id: "swarm_abc123",

  agent_id: "worker-api",

  resource_type: "file",

  resource_id: "src/auth/login.ts",

  timeout_seconds: 300

})

if (claim.success) {

  try {

    // Do the scoped work while the claim is active.

  } finally {

    await snipara_release({

      swarm_id: "swarm_abc123",

      agent_id: "worker-api",

      claim_id: claim.claim_id

    })

  }

}

Claim Parameters

Shared State

Shared state is a versioned key-value store. Use expected_version when a value needs optimistic locking, and snipara_state_poll when an agent needs efficient multi-key monitoring.

await snipara_state_set({

  swarm_id: "swarm_abc123",

  agent_id: "coordinator",

  key: "current_phase",

  value: { phase: "implementation" },

  expected_version: 2

})

const state = await snipara_state_get({

  swarm_id: "swarm_abc123",

  key: "current_phase"

})

const changed = await snipara_state_poll({

  swarm_id: "swarm_abc123",

  keys: ["current_phase", "files_processed", "blocked_count"],

  last_versions: { current_phase: 2, files_processed: 18 }

})

Hierarchical Tasks

Use canonical snipara_htask_* tools for N0-N3 work. Htasks carry owners, priorities, acceptance criteria, evidence requirements, runtime receipts, and audit trails.

Creating Work Items

const task = await snipara_htask_create({

  swarm_id: "swarm_abc123",

  level: "N3_TASK",

  title: "Create JWT utilities",

  description: "Add sign and verify functions",

  owner: "worker-api",

  priority: "P1",

  evidence_required: [

    { type: "test", description: "auth tests pass" }

  ],

  context_refs: ["src/auth/jwt.ts"]

})

Selecting Ready Work

const ready = await snipara_htask_recommend_batch({

  swarm_id: "swarm_abc123",

  owner: "worker-api",

  limit: 1,

  exclude_blocked: true,

  claim_for_agent: "worker-api"

})

const nextTask = ready.tasks?.[0]

if (nextTask) {

  await snipara_htask_complete({

    swarm_id: "swarm_abc123",

    task_id: nextTask.task_id,

    evidence: [

      { type: "test", description: "pnpm test passed" }

    ],

    result: { files_modified: ["src/auth/jwt.ts"] },

    learnings: ["JWT helpers now share one signer"],

    create_memory: true

  })

}

Task States

Inspecting Progress

const tree = await snipara_htask_tree({

  swarm_id: "swarm_abc123",

  task_id: "feature_auth",

  max_depth: 4,

  include_completed: true

})

const metrics = await snipara_htask_metrics({

  swarm_id: "swarm_abc123",

  period_hours: 24

})

const audit = await snipara_htask_audit_trail({

  swarm_id: "swarm_abc123",

  task_id: "htask_abc123"

})

Events

Broadcast events wake or inform live workers. snipara_swarm_events lets polling agents inspect broadcast events and htask audit rows without a Redis subscription.

await snipara_broadcast({

  swarm_id: "swarm_abc123",

  agent_id: "coordinator",

  event_type: "tasks_ready",

  payload: { count: 5 }

})

const recentEvents = await snipara_swarm_events({

  swarm_id: "swarm_abc123",

  event_type: "tasks_ready",

  since: new Date(Date.now() - 60 * 60 * 1000).toISOString(),

  limit: 20

})

Event Types

Plan Limits

Best Practices

• Start simple - Use shared state before adding htask queues.
• Always release claims - Use try/finally when work holds a claim.
• Set bounded TTLs - Prevent deadlocks from crashed agents.
• Keep work scoped - Claims should protect concrete files, modules, or components.
• Complete with evidence - Htask completion should include tests, diffs, proof receipts, or outcome notes.
• Fail closed - Delegated execution still needs explicit approval, handoff receipts, and outcome evidence.

Next Steps