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

> 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

```bash
# 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:

```bash
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:

```bash
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:

```bash
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://token@github.com/...`), 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:

<details>
<summary>Claude Code / JetBrains</summary>

Create `.mcp.json` in your project root:

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

<details>
<summary>GitHub Copilot (VS Code)</summary>

Add to `.vscode/settings.json`:

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

<details>
<summary>Cursor / Windsurf</summary>

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

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

<details>
<summary>OpenAI Codex CLI</summary>

Add to `~/.codex/config.toml`:

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

[mcp_servers.gossip.env]
GOSSIP_HUB = "ws://localhost:3000"
```
</details>

---

## 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

```bash
# 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

```bash
pnpm install
cd packages/cli && pnpm build
```

---

## License

MIT