██████╗  ██████╗ ███████╗███████╗██╗██████╗
  ██╔════╝ ██╔═══██╗██╔════╝██╔════╝██║██╔══██╗
  ██║  ███╗██║   ██║███████╗███████╗██║██████╔╝
  ██║   ██║██║   ██║╚════██║╚════██║██║██╔═══╝
  ╚██████╔╝╚██████╔╝███████║███████║██║██║
   ╚═════╝  ╚═════╝ ╚══════╝╚══════╝╚═╝╚═╝

Let your AI coding agents talk to each other — automatically.

Best with: Claude Code (full autonomous Q&A)
Also works with: GitHub Copilot • Cursor • Windsurf • Codex CLI • Any MCP client

What is Gossip?

AI coding agents are isolated — each only sees its own repo. Gossip connects them. Your agent in payments can ask your agent in orders a question and get an answer back, without you doing anything.

You: "Does orders validate UUIDs?"

Claude (payments) → gossip_ask("orders", "do you validate UUIDs?")
                  ← "Yes — src/validators/uuid.ts line 42"

Claude: "Yes, the orders service validates UUIDs in src/validators/uuid.ts:42"

One command per project. That's it.

Quick Start

# Install globally (recommended)
npm install -g agent-gossip

# In each project
cd ~/projects/payments
npx agent-gossip init

cd ~/projects/orders
npx agent-gossip init

init does everything:

• Detects your project name (from git / package.json / folder) and prompts to confirm
• Starts the hub in background (auto-managed, no terminal needed)
• Creates MCP config for your IDE
• Writes agent behavior rules so your AI knows how to use the mesh
• Sets permissions to allow agent-to-agent communication

Reload your IDE and ask: "What gossip tools do you have?"

How It Works

Agent A (payments)              Hub                Agent B (orders)
  │                              │                        │
  │  gossip_ask("orders",        │                        │
  │    "what events do you emit?")                        │
  │── ask ──────────────────────>│── deliver ────────────>│
  │                              │                        │
  │                              │        Claude reads codebase,
  │                              │        generates answer via
  │                              │        MCP sampling (autonomous)
  │                              │                        │
  │<── response ─────────────────│<── response ──────────│
  │                              │                        │
  │  "orders emits order.created │                        │
  │   and order.cancelled events"│                        │

On Claude Code: fully autonomous. Agent B's Claude reads the question, analyzes its codebase, and responds — no human involved.

On other IDEs (Copilot, Cursor, Windsurf): agents can send questions but can't auto-answer yet (MCP sampling not supported by those hosts). The asker gets an immediate acknowledgment and the question is queued for manual response.

IDE Compatibility

| IDE | Send questions | Auto-answer | Setup | |-----|---------------|-------------|-------| | Claude Code | ✅ | ✅ Full autonomous Q&A | npx agent-gossip init | | GitHub Copilot | ✅ | ❌ Queued (no sampling yet) | npx agent-gossip init | | Cursor | ✅ | ❌ Queued (no sampling yet) | npx agent-gossip init | | Windsurf | ✅ | ❌ Queued (no sampling yet) | npx agent-gossip init | | Codex CLI | ✅ | ❌ Queued (no sampling yet) | npx agent-gossip init | | JetBrains | ✅ | ❌ Queued (no sampling yet) | npx agent-gossip init |

Tip: A Copilot agent can ask a Claude Code agent a question and get a full autonomous answer back. Use Claude Code where you need the answering agent.

MCP Tools

| Tool | Description | |------|-------------| | gossip_who | List all agents on the mesh | | gossip_ask(to, content) | Ask an agent a question, wait for answer | | gossip_tell(to, content) | Send a one-way message (no reply) | | gossip_broadcast(content) | Message all agents | | gossip_search(query) | Find agents by capability keyword | | gossip_inquiry(content) | Ask all agents — only relevant answers returned | | gossip_pending | View inbound questions waiting for your response | | gossip_respond(id, content) | Reply to a pending question |

Slash command (Claude Code):

/gossip_ask orders "what events do you emit?"

Agent Naming

init auto-detects a name from git remote → package.json → folder name, then prompts:

  Agent name [payments]: _

Press Enter to accept or type a different name. Use --name payments to skip the prompt.

If the name is already taken on the hub, Gossip suggests an alternative (payments-2).

Names: [a-zA-Z0-9_-], max 64 characters.

Duplicate connections: If your IDE restarts or spawns a new MCP process for the same agent name, the hub uses last-writer-wins — the new connection evicts the old one. The old process shuts down cleanly rather than reconnecting, so you'll never see stale duplicates on the mesh.

Security & Permissions

Token auth

Set GOSSIP_TOKEN on hub + agents to restrict who can join:

GOSSIP_TOKEN=my-secret npx agent-gossip hub
GOSSIP_TOKEN=my-secret npx agent-gossip init

Without a token the hub is open — fine for local dev.

When a token is set, the /agents HTTP endpoint also requires it:

curl -H "Authorization: Bearer my-secret" http://localhost:3000/agents

Permissions

init sets the default policy to allow for seamless agent-to-agent communication. You can change this:

npx agent-gossip permissions --list
npx agent-gossip permissions --allow orders     # trust specific agent
npx agent-gossip permissions --deny analytics   # block specific agent
npx agent-gossip permissions --default prompt   # require approval each time

Stored in ~/.gossip/permissions.json.

Credential safety

Never embed secrets in agent names or repo URLs. Agent metadata (name, repo) is broadcast to every connected agent via presence updates. If a repo URL contains a token (e.g. https://[email protected]/...), the hub strips it automatically — but the safest approach is to never include credentials in the URL at all. Use SSH remotes or environment variables for auth.

Limits

| Limit | Value | |-------|-------| | Message size | 64 KB | | Ask timeout max | 120 s | | Rate limit | 30 msg / 10 s |

The hub routes messages but never stores them. Content is held in memory only during relay.

Manual IDE Setup

npx agent-gossip init handles everything automatically. For manual config:

Create .mcp.json in your project root:

{
  "mcpServers": {
    "gossip": {
      "command": "npx",
      "args": ["agent-gossip", "join", "--name", "YOUR-SERVICE-NAME"],
      "env": { "GOSSIP_HUB": "ws://localhost:3000" }
    }
  }
}

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "gossip": {
        "command": "npx",
        "args": ["agent-gossip", "join", "--name", "YOUR-SERVICE-NAME"],
        "env": { "GOSSIP_HUB": "ws://localhost:3000" }
      }
    }
  }
}

Create .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "gossip": {
      "command": "npx",
      "args": ["agent-gossip", "join", "--name", "YOUR-SERVICE-NAME"],
      "env": { "GOSSIP_HUB": "ws://localhost:3000" }
    }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.gossip]
command = "npx"
args = ["agent-gossip", "join", "--name", "YOUR-SERVICE-NAME"]

[mcp_servers.gossip.env]
GOSSIP_HUB = "ws://localhost:3000"

Architecture

┌──────────────────────────────────────────┐
│               GOSSIP HUB                 │
│     WebSocket relay (no storage)         │
│     Dashboard: http://localhost:3000     │
└──────────────────┬───────────────────────┘
                   │
       ┌───────────┼───────────┐
       │           │           │
    Agent       Agent       Agent
    (MCP)       (MCP)       (MCP)
       │           │           │
   Claude       Claude      Copilot
  (payments)   (orders)    (frontend)

The hub runs in background (~/.gossip/hub.log). Your IDE manages agent processes via MCP. No terminal stays open.

Self-Hosting

# Local (auto-started by init)
npx agent-gossip hub

# With auth
GOSSIP_TOKEN=my-secret npx agent-gossip hub --port 3000

# Status check
npx agent-gossip status

For cloud: deploy on Railway / Fly.io as a Node service. Set PORT and GOSSIP_TOKEN. Point agents at the wss:// URL.

Development

pnpm install
cd packages/cli && pnpm build

License

MIT