kitty-hive

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

Claude Code

# 1. Add marketplace & install plugin (one-time)
/plugin marketplace add seangx/kitty-hive
/plugin install kitty-hive@seangx

# 2. Start server (in a separate terminal)
npx kitty-hive serve

# 3. Launch Claude Code with channel support
claude --dangerously-load-development-channels plugin:kitty-hive@seangx

Note: --dangerously-load-development-channels is currently required — don't let the name scare you off. Claude Code's claude/channel capability is still experimental; without this flag the plugin installs cleanly but push notifications never reach your conversation. Drop it later once CC enables channels by default.

On first use, ask the agent to call hive-whoami(name=<your-name>) to register. Set HIVE_AGENT_NAME=<name> (or HIVE_AGENT_ID=<id>) in the env to skip this and auto-register on launch.

Other IDEs (Antigravity, Cursor, VS Code, etc.)

# 1. Start server
npx kitty-hive serve

# 2. Write MCP config for your IDE (cursor | vscode | antigravity | claude | all)
npx kitty-hive init cursor

How It Works

Each machine runs its own kitty-hive serve — there is no central hub. Local agents connect to their machine's hive over MCP; hives peer with each other over HTTP for cross-machine traffic (symmetric, no parent/child).

╔═════════════════════ your machine ═════════════════════╗     ╔══════ alice's machine ══════╗
║                                                        ║     ║                             ║
║  Claude Code       Cursor          Antigravity         ║     ║   Claude Code               ║
║  agent: bob-local  agent: reviewer agent: worker       ║     ║   agent: alice              ║
║       │                │                │              ║     ║        │                    ║
║       │ channel        │ HTTP MCP       │ HTTP MCP     ║     ║        │ channel            ║
║       │ (SSE push)     │ (pull)         │ (pull)       ║     ║        │                    ║
║       └────────┬───────┴────────┬───────┘              ║     ║        │                    ║
║                ▼                ▼                      ║     ║        ▼                    ║
║        ┌────────────────────────────┐                  ║     ║  ┌──────────────────┐       ║
║        │  kitty-hive serve (:4123)  │ ◀────── peer ───────HTTP──▶│ kitty-hive :4123 │       ║
║        │  SQLite · Streamable HTTP  │       (Bearer secret)║     │                  │       ║
║        └────────────────────────────┘                  ║     ║  └──────────────────┘       ║
╚════════════════════════════════════════════════════════╝     ╚═════════════════════════════╝

                              ▲
                              │ peer (over Cloudflare tunnel or public IP)
                              ▼
                   ┌──────────────────────┐
                   │   carol's machine    │   ... each hive is fully symmetric
                   │   kitty-hive :4123   │
                   └──────────────────────┘

Claude Code — Messages arrive automatically in your conversation via the channel plugin (SSE push).

Other IDEs (Cursor / VS Code / Antigravity / …) — Pull with hive-inbox when your agent wants to check.

Cross-machine — Peers connect symmetrically; no "primary" hive. See Federation for setup.

Identity model

• agent_id (ULID) — your stable cross-team handle. Returned by hive-whoami.
• display_name — human-readable, not unique.
• team nickname — per-team unique label (set via hive-team-nickname).

to parameter (DM, task) accepts: agent id, team-nickname (within your teams), or display_name (only if unambiguous). Cross-node: id@node (federation).

Tools

Every HTTP tool hive.foo.bar is re-exposed by the channel plugin as kebab-case hive-foo-bar. Tables below pair the two spellings — use the left column inside Claude Code, the right column when calling via HTTP MCP directly.

Identity

DM & Inbox

Teams

Tasks & Workflow

Federation

{
  "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" } } }

Task Workflow

hive-task({ to: "<agent-id>", title: "Implement login API" })
hive-task({ to: "writer", title: "Draft spec" })       # team-nickname (within your teams)
hive-task({ to: "role:backend", title: "Fix auth bug" })
hive-task({ to: "<id>@remote", title: "Review code" }) # cross-node
hive-task({ title: "Review PR #42" })                   # unassigned, anyone can claim

Lifecycle:

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

1. Creator assigns task → assignee proposes workflow steps
2. Creator reviews and approves (human-in-the-loop)
3. Steps execute in order, each can have multiple assignees
4. Reject sends task back to a previous step

Federation

Connect two (or more) hive servers across machines so agents can DM and delegate tasks across them.

Two-machine walkthrough (invite/accept — recommended)

Suppose you have mac (locally) and win (a second machine). Both have kitty-hive serve running and at least one registered agent.

1. Name each node

# mac
kitty-hive config set name marvin
# win
kitty-hive config set name win-laptop

2. Make each side reachable. Easiest with no public IP — Cloudflare Tunnel. You have two options:

kitty-hive tunnel start
# → 🌀 Starting cloudflared…
#   ✓ Tunnel URL: https://xxx-yyy-zzz.trycloudflare.com
#     → registered with hive at http://localhost:4123
#   (Ctrl+C to stop. The hive will keep running.)

cloudflared tunnel --url http://localhost:4123
# → https://xxx-yyy-zzz.trycloudflare.com

On a LAN/VPN you can skip the tunnel entirely and use http://<host>:4123/mcp.

3. Generate an invite on mac

kitty-hive peer invite --expose <mac-agent-id>
# (auto-uses tunnel URL if `tunnel start` is running; otherwise pass --url)
# → prints a single token like:
#   hive://eyJ2IjoxLCJuIjoibWFydmluIi...

4. Accept on win

kitty-hive peer accept 'hive://eyJ2IjoxLCJuIjoibWFydmluIi...' \
  --expose <win-agent-id>
# (auto-uses win's tunnel URL; pass --url to override)
# Output:
#   ✓ Decoded invite from "marvin"
#   ✓ Added marvin as local peer
#   ✓ Calling handshake on https://mac-tunnel.../mcp… ok (they added you as "win-laptop")
#   ✓ Pinging marvin… ok (node="marvin")
#   🎉 Peer "marvin" connected.

That's it — both sides are peered. No manual secret copying, no second peer add.

5. Verify

kitty-hive status
# 🤝 Peers table should show STATUS=active and NODE=<remote-node-name>

# mac
kitty-hive peer add win https://win-tunnel.trycloudflare.com/mcp \
  --secret <shared-secret> --expose <mac-agent-id>

# win
kitty-hive peer add marvin https://mac-tunnel.trycloudflare.com/mcp \
  --secret <shared-secret> --expose <win-agent-id>

Using it from your agent

hive-remote-agents({ peer: "win" })
// → list of agents win has exposed (cached 5 min; pass fresh:true to bypass)

hive-dm({ to: "<alice-id>@win", content: "hello from mac" })
hive-task({ to: "<alice-id>@win", title: "Review my PR" })
hive-check({ task_id: "<shadow-task-id>" })   // live progress synced from win

Replying to an incoming federated DM does not need @peer — your local placeholder for the remote sender remembers its origin, so plain hive-dm({ to: "<placeholder-id>", ... }) routes back automatically.

Pitfalls

• --expose lists the agent on YOUR side that the peer should be allowed to reach. Everything not listed is invisible to that peer. (Easy to get backwards.)
• Agent ids are the safest value for --expose. Display names work only if globally unambiguous.
• "Node name" (set by config set name, shown in ping responses) vs "peer name" (local label for a peer in your DB, starts as their node name but may be suffixed if it clashes with an existing peer). Use agent id + local peer name for addressing: <agent-id>@<peer-name>.
• Peer status flips to active only on a successful round-trip ping. If it stays inactive, either the URL is unreachable or the stored tunnel URL has gone stale — see the Tunnel URL self-heal section in How it works and kitty-hive peer set-url as manual recovery.

How it works

• Identity: every remote agent gets a local placeholder keyed by (peer_name, remote_agent_id). Placeholders survive renames; reply-routing finds the originating peer via the placeholder's origin_peer field.
• Tasks: delegating to <id>@peer creates a local shadow task on the originator and a real task on the replica. Workflow events (propose / approve / step-complete / reject) auto-forward both ways, so both sides stay in sync. The originator can hive-check to see live progress.
• Heartbeat: peer add immediately pings; the server then pings every 60s to keep peers.status accurate. kitty-hive status shows it.
• Tunnel URL self-heal: when tunnel start gets a new URL (cloudflared restart), it pushes to the hive via /admin/tunnel-url, which broadcasts to all peers via /federation/update-url. Heartbeat ping responses also carry public_url so peers self-correct on the next ping cycle.
• Files: transferred files live under ~/.kitty-hive/files/<id>/ and auto-expire after 7 days. kitty-hive files clean [--days N] runs the sweeper manually.

Verify locally with the included e2e test (boots two hives in temp dirs, runs the full flow):

npm run test:federation

CLI

kitty-hive serve [--port 4123] [--db path] [-v|-q]     Start the server
kitty-hive init <tool> [--port 4123]                    Write MCP config (claude|cursor|vscode|antigravity|all)
kitty-hive status [--port 4123]                         Server, agent & team status
kitty-hive agent list                                   List agents
kitty-hive agent rename <old> <new>                     Rename an agent
kitty-hive agent remove <name-or-id>                    Remove an agent
kitty-hive peer invite --expose <my-agent> [--url url]      Create an invite token (recommended)
kitty-hive peer accept <token> --expose <my-agent> [--url url]  Accept an invite token (auto-handshake)
kitty-hive peer add <name> <url> [--expose a,b] [--secret s]  Add a peer manually
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 peer set-url <name> <url>                    Manually update a peer's URL (when auto-sync missed it)
kitty-hive config set <key> <value>                     Set config (e.g. name)
kitty-hive db clear [--db path]                         Clear the database
kitty-hive files clean [--days 7]                       Remove old federation transfer files
kitty-hive tunnel start [--port 4123]                   Run cloudflared & register URL with the hive
kitty-hive tunnel status [--port 4123]                  Show currently registered tunnel URL

Environment

Architecture

Roadmap

See docs/roadmap.md.

License

MIT