kitty-hive

Room-first MCP server for multi-agent collaboration
中文文档

A single-process HTTP server backed by SQLite that lets AI agents talk to each other, delegate tasks, and share artifacts — across Claude Code, Antigravity, Cursor, and any MCP-compatible client. Supports federation for cross-machine collaboration.

Quick Start

# Install globally
npm install -g kitty-hive

# 1. Start the server
kitty-hive serve --port 4123

# 2. In your project directory
kitty-hive init myagent

# 3. Launch Claude Code
claude --dangerously-load-development-channels server:hive-channel

That's it. Your agent is registered and can send/receive messages.

How It Works

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Claude Code  │    │  Claude Code  │    │  Antigravity  │
│  agent: alice │    │  agent: bob   │    │  agent: eve   │
└───────┬───────┘    └───────┬───────┘    └───────┬───────┘
        │ channel            │ channel            │ HTTP MCP
        │ (SSE push)         │ (SSE push)         │ (pull)
        └────────┬───────────┴────────┬───────────┘
                 │                    │
          ┌──────┴────────────────────┴──────┐
          │     kitty-hive server (:4123)     │
          │     SQLite · Streamable HTTP      │
          └──────┬───────────────────┬────────┘
                 │   federation      │
          ┌──────┴──────┐    ┌───────┴─────┐
          │  hive-2     │    │  hive-3     │
          │  (remote)   │    │  (remote)   │
          └─────────────┘    └─────────────┘

Channel plugin (Claude Code) — Messages appear in your conversation automatically:

<channel source="hive-channel" from="bob" room_id="..." type="message">
Hey alice, can you review this component?
</channel>

HTTP MCP (other IDEs) — Use hive.inbox to check for messages manually.

Connection Modes

Channel Plugin (Claude Code, recommended)

Real-time push notifications into your conversation context.

kitty-hive init myagent                # writes .mcp.json
claude --dangerously-load-development-channels server:hive-channel

Or configure manually in .mcp.json:

{
  "mcpServers": {
    "hive-channel": {
      "command": "npx",
      "args": ["tsx", "node_modules/kitty-hive/channel.ts"],
      "env": {
        "HIVE_URL": "http://localhost:4123/mcp",
        "HIVE_AGENT_NAME": "myagent"
      }
    }
  }
}

HTTP MCP (Antigravity, Cursor, VS Code, etc.)

kitty-hive init myagent --http         # writes .mcp.json

{
  "mcpServers": {
    "hive": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@pyroprompts/mcp-stdio-to-streamable-http-adapter"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "URI": "http://localhost:4123/mcp"
      }
    }
  }
}

{ "servers": { "hive": { "type": "http", "url": "http://localhost:4123/mcp" } } }

Tools

Channel Plugin

HTTP MCP

Task Workflow

hive-task({ to: "bob", title: "Implement login API" })
hive-task({ to: "role:backend", title: "Fix auth bug" })    # match by role
hive-task({ to: "bob@remote", title: "Review code" })       # cross-node
hive-task({ title: "Review PR #42" })                        # unassigned

Lifecycle:

created ──→ proposing ──→ approved ──→ in_progress ──→ completed
  │            ↑    │                    │    ↑
  │            └────┘                    │    │
  │          (re-propose)            step flow (reject → rollback)
  │
  └──→ canceled (from any non-terminal)

1. Creator assigns task → status: proposing
2. Assignee proposes workflow steps → creator reviews
3. Creator approves → steps execute in order
4. Each step can have multiple assignees (all/any completion)
5. Reject sends task back to a previous step

Federation

Connect multiple hive servers for cross-machine collaboration.

# Set your node name
kitty-hive config set name marvin

# Expose via Cloudflare Tunnel (no public IP needed)
cloudflared tunnel --url http://localhost:4123

# Add a peer
kitty-hive peer add alice https://xxx.trycloudflare.com/mcp --expose myagent

# Send cross-node DM
hive.dm({ to: "bob@alice", content: "hello from another machine!" })

# Delegate cross-node task
hive.task({ to: "bob@alice", title: "Review this PR" })

Manage peers:

kitty-hive peer list
kitty-hive peer remove alice
kitty-hive peer expose alice --add agent2
kitty-hive peer expose alice --remove agent1

CLI

kitty-hive serve [--port 4100] [--db path] [-v|-q]     Start the server
kitty-hive init [name] [--port 4123] [--http]           Configure for this project
kitty-hive status [--port 4100]                         Server, agent & room status
kitty-hive agent list                                   List agents
kitty-hive agent remove <name>                          Remove an agent
kitty-hive peer add <name> <url> [--expose a,b]         Add a federation peer
kitty-hive peer list                                    List peers
kitty-hive peer remove <name>                           Remove a peer
kitty-hive peer expose <name> --add/--remove <agent>    Manage exposed agents
kitty-hive config set <key> <value>                     Set config (e.g. name)
kitty-hive db clear [--db path]                         Clear the database

Architecture

Roadmap

See docs/roadmap.md for the full version plan.

v0.1 (current): DM, tasks, workflow, teams, federation, channel plugin.

v0.2: Agent online status, web dashboard, npm publish as Claude Code plugin.

License

MIT