Introducing Swarm Mode: Multi-instance Collaboration for PicoClaw

[Zepan]

#119

[nikolasdehor]

Some relevant work already in progress on this:

• PR feature: add swarm mode for multi-instance collaboration #117 — adds swarm mode for multi-instance collaboration (open, +61k/-4k lines — very large diff)
• PR WIP: feat: base multi-agent collaboration framework & shared context #423 — WIP base multi-agent collaboration framework with shared context (+8.6k/-41 lines)
• PR feat: model fallback chain + multi-agent routing #131 (merged) — model fallback chain + multi-agent routing (provides the foundation for agent dispatch)

A few architectural considerations worth discussing before these land:

1. Inter-instance communication: Will swarm instances communicate over HTTP, gRPC, or shared memory? For self-hosted single-machine setups, a simple Unix socket or shared SQLite DB would keep it lightweight. For distributed deployments, something like NATS or Redis pub/sub would be more appropriate.

2. Task decomposition: The key challenge is how to split a user request into subtasks for different agents. OpenAI's Swarm pattern uses a "handoff" model where one agent explicitly transfers control to another. A simpler approach for PicoClaw might be a router agent that dispatches based on tool/skill availability — building on the existing fallback chain from PR feat: model fallback chain + multi-agent routing #131.

3. State consistency: With multiple instances, session state becomes a distributed systems problem. The current file-based sessions.json won't scale for concurrent writes. Even for a v1, a simple lock file or advisory locking mechanism would prevent corruption.

4. Scope: PR feature: add swarm mode for multi-instance collaboration #117 at 61k+ lines is concerning — that's larger than many of PicoClaw's core packages combined. It might be worth splitting into incremental PRs: (a) shared context/memory layer, (b) agent-to-agent messaging, (c) orchestrator/router, (d) channel integration.

The linked discussion #119 has good context on the original vision. Would be great to see a design doc or ADR before the implementation PRs converge.

[Zhaoyikaiii]

Thanks for raising this!

Pico is currently refactoring the channel system, and the ongoing swarm-mode work will be updated on the refactor/channel-system branch as part of that effort. In the meantime, we’ll keep the existing swarm implementation here lightweight to avoid adding too much complexity before the channel refactor is finalized.

Related PR: #709