Skvil Piertotum
MCP + HTTP broker for multi-instance Claude Code communication
Ask AI about Skvil Piertotum
Powered by Claude Β· Grounded in docs
I know everything about Skvil Piertotum. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Skvil-Piertotum
Let your Claude Code instances talk to each other.
Skvil-Piertotum is a lightweight MCP + HTTP broker that connects multiple Claude Code terminals β across projects, machines, WSL, or VMs β so they can exchange messages and share context.
Claude Code (API project) Claude Code (Frontend project)
β β
β sp_send / sp_broadcast β sp_read
ββββββββββββββββ¬βββββββββββββββββββββββββ
β HTTP
ββββββββ΄βββββββ
β broker β
β :4800 β
β β
β messages β
β contexts β
β agents β
βββββββββββββββ
How it works
Two components, zero infrastructure:
broker.js β a tiny Express HTTP server that holds all state in memory (agents, message queues, shared key/value context). Run it once on any machine in your network.
mcp-server.js β an MCP stdio server that runs inside each Claude Code instance. It auto-registers on startup, heartbeats every 30s, and exposes 10 tools so Claude can send/receive messages and share data with other instances.
Quick Start
1. Install
Requirements: Node.js 18 or later (node --version to check).
Option A β via npm (recommended):
npm install -g @skvil/piertotum
Option B β from source:
git clone https://github.com/Skvil-IA/skvil-piertotum
cd skvil-piertotum
npm install
2. Start the broker
Run this once, on any machine accessible to your terminals:
# if installed globally:
skvil-piertotum-broker
# without installing (npx):
npx --package=@skvil/piertotum skvil-piertotum-broker
# custom port:
skvil-piertotum-broker 5000
# from source:
node broker.js
The broker listens on 0.0.0.0 β reachable from any IP on your network.
Tip: Run the broker on your main machine or a server that stays on. Use
hostname -I(Linux/WSL) oripconfig(Windows) to find its IP.
3. Add the MCP server to each Claude Code terminal
Each terminal gets a unique AGENT_ID:
# Terminal 1 β API project
claude mcp add skvil-piertotum \
-e BROKER_URL=http://YOUR-IP:4800 \
-e AGENT_ID=api \
-e AGENT_NAME="API Project" \
-e PROJECT_NAME="my-saas" \
-- skvil-piertotum-mcp
# Terminal 2 β Frontend project
claude mcp add skvil-piertotum \
-e BROKER_URL=http://YOUR-IP:4800 \
-e AGENT_ID=front \
-e AGENT_NAME="Frontend Project" \
-e PROJECT_NAME="my-saas" \
-- skvil-piertotum-mcp
Not installed globally? Replace
skvil-piertotum-mcpwith:npx --package=@skvil/piertotum skvil-piertotum-mcp
If everything is on the same machine, use BROKER_URL=http://localhost:4800.
4. Or configure via ~/.claude.json
{
"mcpServers": {
"skvil-piertotum": {
"type": "stdio",
"command": "skvil-piertotum-mcp",
"env": {
"BROKER_URL": "http://192.168.1.10:4800",
"AGENT_ID": "api",
"AGENT_NAME": "API Project",
"PROJECT_NAME": "my-saas"
}
}
}
}
Each terminal must have a different
AGENT_ID.
Usage examples
Once configured, just talk to Claude naturally:
See who's connected
Register in the broker and show me who else is online
Send context from one project to another
In the API terminal:
I just finished the auth endpoints. Send the full request/response
structure to the 'front' terminal as type 'endpoint'.
In the Frontend terminal:
Read incoming messages and use the endpoint spec to build the Axios services.
Share a schema or config
In the API terminal:
Save the full Prisma schema we just defined to shared context under the key 'db-schema'.
In any other terminal:
Read the shared context 'db-schema' and use it as the source of truth for TypeScript types.
Broadcast an announcement
Broadcast to all agents that the base API URL changed from /api/v1 to /api/v2.
Check system status
Show broker status with all connected agents and their unread message counts.
Available MCP Tools
| Tool | Description |
|---|---|
sp_register | Re-register this terminal (runs automatically on startup) |
sp_list_agents | List all connected agents with staleness indicators |
sp_send | Send a message to a specific agent |
sp_broadcast | Send a message to all connected agents |
sp_read | Read received messages (with pagination and explicit ACK) |
sp_clear | Delete all messages in this agent's queue |
sp_set_context | Save shared data by key (schema, config, endpoints, etc.) |
sp_get_context | Read shared data by key |
sp_list_contexts | List all available context keys |
sp_status | Broker status: uptime, agents, unread counts, context count |
Environment Variables
MCP server (mcp-server.js)
| Variable | Default | Description |
|---|---|---|
BROKER_URL | http://localhost:4800 | URL of the broker |
AGENT_ID | machine hostname | Unique identifier for this instance β must differ per terminal |
AGENT_NAME | SP-{id} | Human-readable display name |
PROJECT_NAME | unknown | Used for grouping agents by project |
Broker (broker.js)
| Variable | Default | Description |
|---|---|---|
BROKER_PORT | 4800 | Port to listen on (also accepts first CLI argument) |
Broker REST API
The broker exposes a plain HTTP API β useful for debugging or integration:
# Status overview
curl http://localhost:4800/status
# List agents
curl http://localhost:4800/agents
# Read messages for an agent (unread only, limit 10)
curl "http://localhost:4800/messages/api?unread=true&limit=10"
# ACK messages by ID
curl -X POST http://localhost:4800/messages/api/ack \
-H "Content-Type: application/json" \
-d '{"ids": ["msg_123", "msg_456"]}'
# Send a message
curl -X POST http://localhost:4800/messages/send \
-H "Content-Type: application/json" \
-d '{"from":"api","to":"front","content":"hello","type":"text"}'
# Shared context
curl http://localhost:4800/context
curl http://localhost:4800/context/db-schema
Full endpoint reference:
POST /agents/register Register an agent
GET /agents List agents
POST /agents/:agentId/heartbeat Heartbeat (404 if not registered)
DELETE /agents/:agentId Deregister agent
POST /messages/send Send to one agent
POST /messages/broadcast Send to all agents except sender
GET /messages/:agentId Read messages (?unread=true, ?limit=N)
POST /messages/:agentId/ack Mark message IDs as read
DELETE /messages/:agentId Clear all messages
POST /context Save context entry
GET /context List context keys
GET /context/:key Read context value
DELETE /context/:key Delete context entry
GET /status Broker overview
Design Notes
- In-memory only β all state is lost if the broker restarts. Agents re-register automatically on the next heartbeat (within 30s). For persistence, adapt the broker to use SQLite.
- Resource limits β max 100 agents, 200 messages per queue (oldest dropped), 1000 context keys, 100 KB per context value, 512 KB per message.
- Stale agent cleanup β agents that miss 3 heartbeats (90s) are automatically removed.
- Message types β
text,code,schema,endpoint,config. Used by agents to route and handle responses appropriately. - ES modules β both files use
import/export("type": "module"inpackage.json).
Use Cases
Monorepo with multiple services Each service runs in its own terminal. When the API changes a contract, it notifies the frontend automatically.
Distributed setup (PC + WSL + VM) Run the broker on the host machine. WSL and VM terminals connect via the host IP.
Multi-agent orchestration
An orchestrator terminal delegates tasks to worker terminals. Workers report status via shared context. The orchestrator checks sp_get_context("{worker}-status") before assigning new work.
Team knowledge sharing Each developer registers their terminal. Share schemas, decisions, and context across the team in real time β without copy-pasting into chat.
Contributing
Issues and pull requests are welcome. For non-trivial changes, please open an issue first to discuss the approach.
Why "Piertotum"?
License
MIT β see LICENSE.
References
The tool design, security hardening, and MCP best practices in this project were based on:
