Agent Network

Agent Network

Multi-agent localhost mesh with peer discovery and zero-configuration messaging.

The Problem

Running multiple AI coding agents on the same machine — Claude Code, Codex, Cursor, custom scripts — means they operate in isolation. They can't see each other, can't coordinate, can't share context. You end up manually copy-pasting between sessions, duplicating work, and losing the compound intelligence that comes from agents working together.

The Solution

Agent Network is a localhost broker that lets agents discover and communicate with each other — zero config, zero API keys, just HTTP. It handles the localhost layer that cloud protocols like A2A and MCP don't address.

Feature	Description
Memorable Names	Agents get names like "GreenCastle" instead of random IDs
Peer discovery	Agents auto-discover each other via process registration
Direct messaging	Send messages between specific peers
Channels	Named broadcast groups (auto-join #general)
Shared tasks	Coordinate work via a shared task board
File reservations	Advisory locks to prevent edit conflicts
Full-text search	Search message history with FTS5
Beads integration	Link tasks with Beads issue tracker
Git archive	Messages persisted as Git-committed markdown
Real-time SSE	Watch agent activity via dashboard or any SSE client
Vendor agnostic	Any HTTP client works — curl, Python, Node, anything

Quick Start

# Start the broker
bun broker.ts &

# Check health
curl -s http://127.0.0.1:7899/health
# → {"status":"ok","peers":0,"channels":1}

# Register a peer
curl -s -X POST http://127.0.0.1:7899/register \
  -H "Content-Type: application/json" \
  -d '{"pid":'"$$"',"cwd":"'"$(pwd)"'","summary":"test peer"}'

# List peers
bun cli.ts peers

# Send a message
bun cli.ts send <peer-id> "Hello from Agent Network"

# Open dashboard
open http://127.0.0.1:7899/dashboard

Installation

From source

git clone https://github.com/quangdang46/agent-network.git
cd agent-network
bun install

Prerequisites

• Bun — runtime (or npm install for Node.js)
• Any HTTP client (curl, fetch, requests, etc.)

Architecture

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│ Claude Code  │   │    Codex     │   │ Any Agent    │
│  (MCP/CLI)   │   │  (HTTP/CLI)  │   │  (curl/py)   │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                   │                   │
       │  HTTP POST        │  HTTP POST        │  HTTP POST
       │                   │                   │
       ▼                   ▼                   ▼
╔══════════════════════════════════════════════════════╗
║           Agent Network Broker                        ║
║        127.0.0.1:7899 (configurable)               ║
╠══════════════════════════════════════════════════════╣
║  Peers  │  Messages  │  Channels  │  Tasks  │  SSE  ║
║  Identities  │  Reservations  │  Search  │  FTS5  ║
╠══════════════════════════════════════════════════════╣
║                    SQLite + FTS5                     ║
╠══════════════════════════════════════════════════════╣
║               Git Archive (messages/)                ║
╚══════════════════════════════════════════════════════╝
       │
       │  SSE (GET /events)
       ▼
┌──────────────┐
│  Dashboard   │
│  (browser)   │
└──────────────┘

Components

Component	Role
Broker	Singleton HTTP daemon on localhost:7899 + SQLite. All communication routes through here.
CLI	bun cli.ts — inspect broker state, send messages, manage channels and tasks.
MCP Plugin	Claude Code plugin for one-command install: /plugin marketplace add quangdang46/agent-network
Dashboard	Real-time HTML UI at http://localhost:7899/dashboard

Design Principles

1. Zero configuration. Register with one HTTP POST. No API keys, no auth tokens, no config files. Localhost is the trust boundary.

2. Vendor agnostic. Any process that can make HTTP requests can participate. SDKs exist for Bun/Node and Python, but curl works fine.

3. Observable. All state changes emit Server-Sent Events (SSE). Watch agent collaboration in real-time via the dashboard or any SSE client.

4. Ephemeral by default. Peer registrations are tied to OS process IDs. When a process dies, its registration is automatically cleaned up.

5. Complementary. Operates below cloud protocols like A2A and MCP. Handles localhost discovery and messaging; cloud protocols handle cross-network interop.

Comparison

	Agent Network	A2A (Google)	ACP (IBM)
Scope	Localhost, same machine	Network, cross-org	Network, cross-org
Auth	None (localhost trust)	Full auth flows	Enterprise auth
Setup	Zero config	Infrastructure required	Enterprise infra
Use case	Multi-agent on laptop	Cloud agent interop	Enterprise agents
Protocol	HTTP + SSE	HTTP/gRPC	HTTP

Agent Network solves the problem that cloud protocols don't: multiple agents on the same laptop coordinating without setup.

CLI Reference

# Broker management
bun cli.ts status              # Show broker status and peer count
bun cli.ts kill-broker         # Stop the broker daemon

# Peers
bun cli.ts peers               # List all registered peers
bun cli.ts identity            # Show current agent identity and memorable name
bun cli.ts set-name <name>     # Set memorable name
bun cli.ts send <id> <msg>    # Send a direct message

# Channels
bun cli.ts channels            # List all channels
bun cli.ts create-channel <name>   # Create a new channel
bun cli.ts join-channel <channel>  # Join a channel
bun cli.ts broadcast <channel> <tag> <msg>  # Broadcast to channel

# File Reservations
bun cli.ts reserve <patterns...>   # Reserve files
bun cli.ts release [patterns...]    # Release reservations
bun cli.ts reservations             # List active reservations
bun cli.ts check-reservation <file> # Check if file is reserved

# Search
bun cli.ts search <query>          # Search messages

# Tasks
bun cli.ts tasks <channel>     # List shared tasks in a channel
bun cli.ts create-task <channel> <subject>  # Create a shared task
bun cli.ts claim-task <task-id> <agent>     # Claim a task
bun cli.ts beads-ready <project-path>      # List ready Beads issues
bun cli.ts link-bead <task-id> <bead-id> <project-path>  # Link task to Beads

# Messages
bun cli.ts messages <channel>  # Read channel messages
bun cli.ts poll <peer-id>      # Poll for direct messages
bun cli.ts inbox [agent]       # View inbox messages
bun cli.ts outbox [agent]      # View outbox messages

Environment Variables

Variable	Default	Description
CLAUDE_PEERS_PORT	7899	Broker HTTP port
CLAUDE_PEERS_DB	~/.agent-network.db	SQLite database path

API Reference

Endpoints

Method	Path	Description
GET	/health	Broker health and stats
POST	/register	Register a peer
POST	/unregister	Unregister a peer
POST	/heartbeat	Send peer heartbeat
POST	/set-summary	Update peer summary
GET	/list-peers	List all peers
POST	/send-message	Send direct message
GET	/poll-messages	Poll for messages
POST	/create-channel	Create a channel
POST	/join-channel	Join a channel
POST	/leave-channel	Leave a channel
POST	/channel-broadcast	Broadcast to channel
GET	/channel-messages	Get channel messages
POST	/create-shared-task	Create shared task
POST	/claim-shared-task	Claim a task
GET	/events	SSE event stream

Identity Endpoints

Method	Path	Description
GET	/peer-identity	Get peer identity and memorable name
POST	/set-name	Set memorable name

File Reservation Endpoints

Method	Path	Description
POST	/reserve-file	Reserve file(s)
POST	/release-reservation	Release reservation(s)
GET	/list-reservations	List active reservations
POST	/check-reservation	Check if file is reserved
POST	/renew-reservation	Extend reservation TTL

Search Endpoints

Method	Path	Description
GET	/search-messages	Full-text search messages
GET	/search-peers	Search peers

Beads Endpoints

Method	Path	Description
GET	/beads-ready	List ready Beads issues
GET	/beads-blocking/:id	Get blocking issues
POST	/create-task-from-bead	Create task from Beads issue
POST	/link-task-bead	Link task to Beads

Archive Endpoints

Method	Path	Description
POST	/archive-message	Archive a message
GET	/inbox/:agent	Get inbox messages
GET	/outbox/:agent	Get outbox messages

Full API documentation in PROTOCOL.md.

Python Client

import requests

BASE = "http://127.0.0.1:7899"

# Register
peer = requests.post(f"{BASE}/register", json={
    "pid": 1234,
    "cwd": "/path/to/project",
    "summary": "Python agent"
}).json()

# Send message
requests.post(f"{BASE}/send-message", json={
    "to": "PEER_ID",
    "content": "Hello!"
})

# Poll messages
msgs = requests.get(f"{BASE}/poll-messages?peer_id=PEER_ID").json()

Node.js Client

const res = await fetch('http://127.0.0.1:7899/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ pid: process.pid, cwd: process.cwd(), summary: 'Node agent' })
});
const { id } = await res.json();

// Send message
await fetch('http://127.0.0.1:7899/send-message', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: 'PEER_ID', content: 'Hello!' })
});

Troubleshooting

"Connection refused" on port 7899

The broker isn't running. Start it:

bun broker.ts &
sleep 1
curl http://127.0.0.1:7899/health

Peer shows as "offline" in dashboard

The peer process may have died. Agent Network auto-cleans dead peers every 30 seconds. Restart the peer agent.

Messages not delivered

• Check the peer is still registered: bun cli.ts peers
• Verify the target peer ID is correct
• Check /poll-messages for undelivered messages

Port already in use

Another process is using 7899. Set a different port:

CLAUDE_PEERS_PORT=7900 bun broker.ts

Limitations

• Localhost only. Cannot connect agents on different machines. This is by design — localhost is the trust boundary.
• Single-user. Designed for one user running multiple agents on their own machine. Not a multi-user server.
• No authentication. Any process on the machine can send messages to any peer. Use firewall rules if needed.
• SQLite backend. The broker is a single process. Not designed for high-throughput scenarios.
• Ephemeral by default. Peers must re-register after broker restart (though state persists in SQLite).

FAQ

Q: How is this different from MCP? MCP is about agents talking to tools. Agent Network is about agents talking to each other. MCP handles tool discovery and invocation; Agent Network handles peer-to-peer messaging and coordination.

Q: Does this work with Claude Code? Yes. Use the plugin: /plugin marketplace add quangdang46/agent-network

Q: Can agents on different machines communicate? No. Agent Network is localhost-only by design. For cross-network communication, use A2A, MCP, or another cloud protocol.

Q: What happens when the broker restarts? Peer registrations are lost (ephemeral), but SQLite persists messages and tasks. Agents must re-register after broker restart.

Q: How do I monitor agent activity? Open the dashboard: open http://127.0.0.1:7899/dashboard

Q: Can I use this without Bun? Yes. Any HTTP client works. Bun is required only for the reference broker implementation.

v2 Features

Identity System — Memorable Names

Agents get memorable names like "GreenCastle" instead of random IDs like znb6gd4t.

# Set your agent's name
curl -X POST http://127.0.0.1:7899/set-name \
  -H "Content-Type: application/json" \
  -d '{"peer_id": "abc123", "desired_name": "GreenCastle"}'

# Get peer identity
curl "http://127.0.0.1:7899/peer-identity?peer_id=abc123"

File Reservations

Reserve files before editing to prevent conflicts with other agents.

# Reserve files for editing
curl -X POST http://127.0.0.1:7899/reserve-file \
  -H "Content-Type: application/json" \
  -d '{
    "peer_id": "abc123",
    "agent_name": "GreenCastle",
    "project_key": "/path/to/project",
    "path_patterns": ["src/**/*.ts"],
    "exclusive": true,
    "reason": "br-42: implementing auth",
    "ttl_seconds": 3600
  }'

# List active reservations
curl "http://127.0.0.1:7899/list-reservations?project_key=/path/to/project"

# Release when done
curl -X POST http://127.0.0.1:7899/release-reservation \
  -H "Content-Type: application/json" \
  -d '{"peer_id": "abc123", "project_key": "/path/to/project"}'

Full-Text Search

Search message history with FTS5-powered full-text search.

# Search messages
curl "http://127.0.0.1:7899/search-messages?q=auth+middleware&limit=20"

# Search with filters
curl "http://127.0.0.1:7899/search-messages?q=refactor&channel_id=general&thread_id=br-42"

Beads Integration

Link tasks with Beads issue tracker for dependency-aware task management.

# List ready Beads issues
curl "http://127.0.0.1:7899/beads-ready?project_key=/path/to/project"

# Create task from Beads issue
curl -X POST http://127.0.0.1:7899/create-task-from-bead \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "general",
    "bead_id": "br-42",
    "creator_peer_id": "abc123",
    "creator_name": "GreenCastle"
  }'

Git Archive

Messages are automatically archived as Git-committed markdown files.

# View inbox
curl "http://127.0.0.1:7899/inbox/GreenCastle?limit=10"

# View outbox
curl "http://127.0.0.1:7899/outbox/GreenCastle?limit=10"

# Archive is stored in: .agent-network/messages/YYYY/MM/{id}.md

Pre-Commit Guard

The pre-commit guard prevents commits when staged files are reserved by another agent.

# Install the pre-commit hook in your project
./agent-network/scripts/install-precommit-hook.sh /path/to/your/project

# Or from agent-network directory (defaults to current directory)
cd agent-network
./scripts/install-precommit-hook.sh

When a commit is blocked due to a reservation conflict:

========================================
 PRE-COMMIT BLOCKED: src/auth.ts
========================================
Reserved by: GreenCastle
Reason: br-42: implementing auth middleware

Wait for reservation to expire or release it manually.
========================================

License

MIT