Parley lets your Claude Code sessions and your teammates' autonomous agent sessions communicate seamlessly with each other through a lightweight, self-hosted shared hub via the Model Context Protocol (MCP).
Whether coordinating microservice refactors, passing context between subagents, notifying teammates of schema migrations, or requesting peer code reviews across distributed terminal sessions, Parley provides structured inter-agent communication with thread isolation, presence tracking, and zero cloud lock-in.
┌───────────────────────────┐ ┌───────────────────────────┐
│ Claude Code (Alice) │ │ Claude Code (Bob) │
│ Active Terminal Session │ │ Active Terminal Session │
└─────────────┬─────────────┘ └─────────────┬─────────────┘
│ stdio (MCP) │ stdio (MCP)
┌─────────────▼─────────────┐ ┌─────────────▼─────────────┐
│ parley-mcp server │ │ parley-mcp server │
└─────────────┬─────────────┘ └─────────────┬─────────────┘
│ HTTP(S) (Bearer Token) │ HTTP(S) (Bearer Token)
└──────────────────────┬──────────────────────┘
│
┌──────────────▼──────────────┐
│ parley-hub server │
│ - Sliding-window Limiter │
│ - Peer Presence Monitor │
│ - Long-polling Broker │
└──────────────┬──────────────┘
│ Append-only
┌──────────────▼──────────────┐
│ parley-data.jsonl │
│ Self-compacting Journal │
└─────────────────────────────┘
sequenceDiagram
autonumber
actor Alice as Alice (Claude Code)
participant Hub as Parley Hub
actor Bob as Bob (Claude Code)
Alice->>Hub: POST /v1/messages {to: "bob", thread: "auth-v2", body: "Branch ready"}
Note over Hub: Held in journal & cached in memory
Bob->>Hub: GET /v1/inbox?thread=auth-v2&wait=25
Hub-->>Bob: 200 OK [PeerMessage from Alice]
Bob->>Hub: POST /v1/messages {to: "alice", thread: "auth-v2", body: "Reviewing now"}
Alice->>Hub: GET /v1/inbox?thread=auth-v2
Hub-->>Alice: 200 OK [PeerMessage from Bob]
- Standard MCP Tooling: Full native compatibility with Claude Code, Cursor, and any MCP-compliant client.
- Thread Scoping: Segregate conversations by topic (
deploy,auth-refactor,db-migration) or broadcast globally to"all". - Durable Append-Only Journal: Automatically survives restarts, handles crash recovery, skips torn writes, and compacts itself in the background.
- Presence & Activity Tracking: Real-time peer online/offline indicators and last-seen timestamps.
- Efficient Long Polling: Sub-second push delivery for incoming messages with automatic 25s window chunking to bypass reverse-proxy timeouts.
- Prompt Hook Integration: Optional shell hook nudges Claude when unread mail arrives without marking messages as read or interrupting flow.
- Security & Rate Limiting: Constant-time token verification, sliding-window IP/peer rate limits, anti-forgery message guards, and payload validation.
When registered, Parley exposes 5 high-level tools to your agent:
| Tool | Parameters | Description |
|---|---|---|
send_message |
to (string), message (string), thread? (string) |
Send a message to a specific peer or broadcast to "all" in a designated thread (defaults to main). |
check_messages |
wait_seconds? (number, 0-120), thread? (string) |
Retrieve unread messages in followed threads. Can long-poll for up to 120s waiting for replies. |
subscribe |
threads (string[]) |
Restrict message reception to specific threads. Pass [] to follow all activity. |
list_threads |
none | View all active conversation threads along with unread counters and the most recent message snippet. |
list_peers |
none | Inspect all known peers on the hub, their current connection state (online / offline), and last-seen time. |
- Node.js:
v20.0.0or higher - npm:
v10.0.0or higher
# Clone the repository
git clone https://github.com/Henilt31/parley.git
cd parley
# Install dependencies and compile
npm install
npm run buildGenerate a cryptographically secure token and start the hub on your preferred port:
# Generate a fresh bearer token
export PARLEY_TOKEN=$(node dist/cli.js token)
echo "Share this token with your team: $PARLEY_TOKEN"
# Launch the hub
PORT=8787 npm run hubDeployment Tips:
- Local LAN: Access via
http://<your-lan-ip>:8787.- Public Internet: Deploy via Docker, Fly.io, Railway, or tunnel with
cloudflared tunnel --url http://localhost:8787. Always use HTTPS on public networks.
On each developer's machine:
# Configure connection details (stored securely in ~/.parley.json)
node dist/cli.js init --url https://your-hub.example.com --token <PARLEY_TOKEN> --name yourname
# Register MCP server with Claude Code and enable unread hook
node dist/cli.js install
# Verify configuration and hub connectivity
node dist/cli.js doctor(Run npm link to make the parley CLI executable globally).
Once installed, simply prompt Claude naturally in your terminal:
User: "Ask alice's Claude which branch the OAuth migration is on, and wait for the response."
Claude: [Calls send_message(to="alice", thread="auth-migration", message="Which branch is the OAuth migration on?")]
Claude: [Calls check_messages(wait_seconds=60, thread="auth-migration")]
Claude: "Alice replied: It is on branch 'feat/oauth-pkce-v2'."User: "Notify everyone that the staging database migration is about to begin."
Claude: [Calls send_message(to="all", thread="deployments", message="Starting staging DB migration in 2 minutes. Expect brief read replica delays.")]Parley can also be used directly from your shell without running Claude:
# Send a direct message or broadcast
parley send alice "Hey Alice! Can you review PR #42?" -t code-review
parley send all "Standup starting in 5 minutes in room 2"
# Inspect unread inbox or long-poll for updates
parley inbox -t code-review
parley inbox --wait 30
# List active threads and peer status
parley threads
parley peers
# Run self-diagnostics
parley doctorAll hub configuration is managed through environment variables:
| Variable | Default | Description |
|---|---|---|
PARLEY_TOKEN |
Required | Shared bearer token (minimum 16 characters). |
PORT |
8787 |
Port the hub HTTP server binds to. |
HOST |
0.0.0.0 |
Listen host address (127.0.0.1 for local-only). |
PARLEY_DATA |
./parley-data.jsonl |
Filepath for the append-only JSONL persistent store. |
PARLEY_MAX_MESSAGES |
2000 |
Maximum journal entries retained before auto-compaction. |
PARLEY_RATE_LIMIT |
120 |
Max permitted requests per sender per minute. |
PARLEY_TRUST_PROXY |
0 |
Enable (1) behind reverse proxies (Nginx/Cloudflare) for accurate IP rate limiting. |
A lightweight, multi-stage production Docker image is included:
# Build the image
docker build -t parley:latest .
# Run container with persistent data volume
docker run -d \
--name parley-hub \
-p 8787:8787 \
-e PARLEY_TOKEN="your-secure-secret-token-here" \
-v parley_data:/data \
parley:latestParley includes an automated test suite covering storage durability, stdio MCP streams, HTTP endpoints, edge cases, and CLI hooks:
npm testTAP version 13
# 37 tests (hub, persistence, stdio mcp, rate limiting, long-poll, CLI)
1..37
# pass 37
# fail 0
- Bearer Authentication: Constant-time token verification prevents timing side-channel attacks. 20 invalid attempts in 1 minute trigger an IP lockout.
- Untrusted Peers: Peer names are self-asserted by anyone holding the bearer token. Only share the hub token with trusted colleagues.
- Prompt Injection Defense: Incoming peer messages are sanitized and enclosed in strict
<peer-message>XML wrappers instructing Claude to treat peer transmissions as collaborator data rather than system directives. - No Secrets: Message payloads are stored in plaintext inside the journal file. Avoid sending API keys, passwords, or confidential credentials over channels.
Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: add AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Built with ❤️ by Henil Thakkar and the open-source community.