[KongchangAI]
· 3 min read· 1,513 words

p2p-swarm: An Open-Source P2P Network for Decentralized Claude Code Agent Collaboration

p2p-swarm: An Open-Source P2P Network for Decentralized Claude Code Agent Collaboration

p2p-swarm uses an encrypted P2P network to let independent Claude Code sessions team up without a central server.

p2p-swarm is an open-source project that lets Claude Code sessions on different computers automatically discover each other, form teams, and collaborate on projects over an encrypted peer-to-peer network—without a centralized orchestration server. It organizes collaboration through "swarms": a creator sets a goal and shares a swarm:// invite link, and other agents join, plan automatically, execute tasks in parallel, and keep each other in check through peer review. Built on Hyperswarm, it combines Kademlia DHT node discovery, UDP hole punching for direct connections, Noise protocol encryption, Ed25519-signed events, and a replicated event log, letting each node independently reconstruct the shared task state. Temporary leases ensure that tasks can be reclaimed after a node goes offline. The project uses the MIT license and offers a Claude Code plugin, CLI, and web dashboard, but it is still early-stage—preventing malicious nodes under open joining and the effectiveness of adversarial peer review remain to be validated.

If AI agents running on different computers could automatically discover each other, form teams, and complete a project together—without relying on any centralized orchestration server—that's exactly the vision the open-source project p2p-swarm aims to realize. It builds a peer-to-peer network for autonomous AI agent collaboration, letting independent Claude Code sessions work together over encrypted P2P connections.

p2p-swarm Reddit launch post

From Centralized Orchestration to Decentralized Swarms

Most mainstream AI agent collaboration solutions today—whether multi-agent frameworks or workflow engines—rely on a centralized controller to distribute tasks and aggregate results. The bottleneck of this architecture is obvious: the controller becomes a single point of failure, all communication and state synchronization must pass through it, and scalability and fault tolerance are limited.

p2p-swarm takes a different approach. You create a "swarm," set a goal—such as building an app or writing documentation—and then share a swarm:// invite link. Other participants simply run a join command in their own Claude Code to connect to the same distributed network. Once connections are established, agents organize the work themselves; the system has no permanent leader and no central scheduler. Each node maintains a copy of the shared task state and reaches eventual consistency through an event log.

This design pushes agent collaboration from a "master-slave model" toward a "peer-to-peer model," opening up new possibilities for cross-organization and cross-region AI collaboration.

Workflow: Five Steps to Collaboration

The p2p-swarm collaboration flow is clear and closely mirrors how real teams work:

  1. Create a swarm: start a swarm and define the goal;
  2. Connect agents: share the swarm:// link so other Claude Code sessions join the same distributed network;
  3. Automatic planning: one agent breaks the goal into subtasks based on the number of available workers;
  4. Parallel execution: agents claim different tasks and make progress simultaneously;
  5. Peer review: idle agents review each other's results and challenge work that needs improvement;
  6. Final delivery: the completed pieces are merged into a single result.

The "peer review" stage is particularly noteworthy—it creates quality checks and balances among agents rather than simply stacking outputs. This mechanism is especially important in a decentralized environment, because without a central quality-control node, review can only be performed by peers.

Technical Foundation: Hyperswarm and Event Logs

p2p-swarm is built on Hyperswarm, combining several decentralized networking technologies:

  • Kademlia DHT for decentralized node discovery;
  • UDP hole punching to enable direct connections between machines;
  • Noise protocol encryption to secure communication;
  • Ed25519 identities and signed events to ensure message authenticity;
  • Replicated event logs to keep participants' state in sync;
  • Content-addressed file sharing with SHA-256 verification.

Each node independently reconstructs the same task state from the shared event history, which means the system relies on no central server to coordinate consistency. Agents can also exchange project files directly, fetching only the data they need rather than uploading everything to a central node. This "content-addressed + pull-on-demand" model outperforms traditional centralized file distribution in both bandwidth and privacy.

Kademlia DHT is a distributed hash table (DHT) protocol used to achieve node discovery and routing in peer-to-peer networks without a central server. It maps nodes and resource keys into the same 160-bit address space; each node maintains a routing table and progressively approaches the target node using an XOR distance metric, thereby locating the node responsible for a given key within O(log N) hops. Kademlia's node discovery is self-organizing: a new node only needs to know one bootstrap node to join the network and gradually fill in its routing table. In p2p-swarm, the Kademlia DHT handles the discovery role of "who is online and who is under which topic," allowing agents to find each other without preconfigured addresses.

UDP hole punching is a NAT traversal technique that allows two machines behind different private networks to establish direct UDP communication. The principle is that both parties first exchange their public IPs and ports through a publicly reachable coordination server (or DHT node), then simultaneously send UDP packets to each other, causing their respective NAT devices to open mappings in the outbound direction so that the other party's inbound packets can pass through. Hole punching does not succeed under all NAT types (symmetric NATs often require relaying), but in most home and office network environments it can significantly reduce dependence on central relays. In p2p-swarm, UDP hole punching lets Claude Code sessions on different computers establish direct peer-to-peer connections wherever possible, reducing relay latency and bandwidth costs.

The Noise protocol is a security framework for building encrypted communication protocols, not a single protocol. By combining Diffie-Hellman key exchange, symmetric encryption, and hash functions, it supports multiple handshake patterns (such as NN, XX, IK, etc.), each with different trade-offs in identity authentication, forward secrecy, and number of interaction rounds. Noise is designed to be simple, provably secure, and easy to implement, and has been adopted by systems such as WireGuard and Signal. In p2p-swarm, the Noise protocol establishes encrypted channels between two peer connections, ensuring that task content, review comments, and file transfers are encrypted above the transport layer—so even if traffic passes through untrusted relay nodes, it cannot be eavesdropped on or tampered with.

Fault Tolerance: What Happens When a Node Goes Offline?

A decentralized system must answer one question: if an agent goes offline midway through a task, will the work be interrupted?

p2p-swarm addresses this with a temporary lease mechanism. When a task is assigned to an agent, it comes with a lease; if the agent disappears before completing it, the task becomes claimable again once the lease expires and is taken over by another agent. The swarm does not depend on the machine that originally created it staying online—after the creator exits, the network can continue to operate.

This design clearly distinguishes p2p-swarm from centralized orchestration solutions in terms of fault tolerance: with the latter, once the controller goes down, the entire collaboration process comes to a halt.

A replicated event log is a mechanism that lets multiple nodes agree on state without a central coordinator. Each node appends locally generated operations to its own log as events and propagates them to other nodes via gossip or broadcast protocols; all nodes apply events in some deterministic order (such as ordering based on timestamps and node IDs) and ultimately reconstruct the same state. This pattern belongs to the "eventual consistency" family along with CRDTs (conflict-free replicated data types) and operational transformation (OT), but event logs are more general: they do not prescribe the data structure of the state, but instead treat "what happened" as the single source of truth. In p2p-swarm, actions such as tasks being claimed, leases expiring, and reviews passing are all written to the log as events, and nodes independently derive from it which tasks are currently claimable and which are complete—avoiding any central server to adjudicate state.

A temporary lease is a classic primitive in distributed systems for handling failure detection and resource reclamation. It is essentially a time-bounded authorization: the grantor promises not to grant the same resource to anyone else during the lease period, while the holder promises to complete the work or renew before the lease expires. If the holder crashes or loses connectivity, the lease naturally expires and the resource becomes available again, without relying on an explicit "death notification"—this is especially important in asynchronous networks, where a node cannot distinguish "the other party is dead" from "the other party is just slow." The cost of leases is time: reclamation must wait for the lease to expire, so lease duration must be balanced between "speed of failure recovery" and "risk of mistakenly reclaiming a healthy task." p2p-swarm applies this mechanism to task claiming, so that tasks can be safely taken over by other nodes after an agent goes offline.

Getting Started and Ecosystem

The project uses the MIT license, supports macOS, Linux, and Windows, and provides a Claude Code plugin, a CLI, and a local web dashboard. The commands to install the plugin in Claude Code are:

/plugin marketplace add p2pswarm/p2p-swarm
/plugin install swarm@p2p-swarm

Once installed, you can create swarms, invite other agents, and collaborate around a shared goal.

Significance and Open Questions

The value of p2p-swarm lies in extending "multi-agent collaboration" from a single machine or cluster to the open network. Claude Code sessions from different organizations and locations can temporarily team up around a goal and then disperse when done—an elasticity that centralized solutions struggle to provide.

However, decentralized collaboration also brings new challenges: how does an open-join swarm prevent malicious nodes from submitting low-quality or harmful content? The effectiveness of peer review in adversarial environments remains to be verified; whether event-log consistency can hold up in a dynamic network with frequent node joins and exits is also worth testing in practice. The project is still at an early stage, and these questions await answers from the community through real-world use.

For developers interested in multi-agent systems, decentralized infrastructure, and AI coding tools, p2p-swarm offers a noteworthy experimental direction: when agents no longer need a "boss," how far can they collaborate?

#p2p-swarm#Claude Code#P2P network#multi-agent collaboration#Hyperswarm#decentralized AI agents#Kademlia DHT
Share:

Related articles