kitty-hive 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+<p align="center">
+  <h1 align="center">kitty-hive</h1>
+  <p align="center">
+    Room-first MCP server for multi-agent collaboration
+    <br />
+    <a href="./README.zh.md">中文文档</a>
+  </p>
+</p>
+
+---
+
+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
+
+```bash
+# 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.
+
+```bash
+kitty-hive init myagent                # writes .mcp.json
+claude --dangerously-load-development-channels server:hive-channel
+```
+
+Or configure manually in `.mcp.json`:
+
+```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.)
+
+```bash
+kitty-hive init myagent --http         # writes .mcp.json
+```
+
+<details>
+<summary>Manual configuration for each IDE</summary>
+
+**Antigravity** (`mcp_config.json`):
+```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"
+      }
+    }
+  }
+}
+```
+
+**Cursor**: Settings → MCP Servers → `{ "hive": { "url": "http://localhost:4123/mcp" } }`
+
+**VS Code Copilot** (`.vscode/mcp.json`):
+```json
+{ "servers": { "hive": { "type": "http", "url": "http://localhost:4123/mcp" } } }
+```
+
+</details>
+
+## Tools
+
+### Channel Plugin
+
+| Tool | Description |
+|------|-------------|
+| `hive-dm` | Send a direct message |
+| `hive-inbox` | Check unread messages |
+| `hive-task` | Create & delegate a task |
+| `hive-claim` | Claim an unassigned task |
+| `hive-tasks` | List tasks (board view) |
+| `hive-check` | Check task status |
+| `hive-rooms` | List your rooms |
+| `hive-room-info` | Room details + members |
+| `hive-events` | Fetch room event history |
+| `hive-team-create` | Create a team room |
+| `hive-team-join` | Join a team (by name or ID) |
+| `hive-team-list` | List all teams |
+| `hive-propose` | Propose workflow steps |
+| `hive-approve` | Approve workflow (creator only) |
+| `hive-step-complete` | Complete a workflow step |
+| `hive-reject` | Reject & rollback a step |
+| `hive-peers` | List federation peers |
+| `hive-remote-agents` | List agents on a remote peer |
+
+### HTTP MCP
+
+| Tool | Description |
+|------|-------------|
+| `hive.start` | Register agent + join lobby |
+| `hive.dm` | Send a direct message (supports `agent@node`) |
+| `hive.task` | Create & delegate (supports `agent@node`) |
+| `hive.task.claim` | Claim an unassigned task |
+| `hive.tasks` | List tasks (board view) |
+| `hive.check` | Check task status |
+| `hive.inbox` | Check unread messages |
+| `hive.room.events` | Fetch room events |
+| `hive.room.list` | List your rooms |
+| `hive.room.info` | Room details + members |
+| `hive.team.create` | Create a team room |
+| `hive.team.join` | Join a team (by name or ID) |
+| `hive.team.list` | List all teams |
+| `hive.workflow.propose` | Propose workflow steps |
+| `hive.workflow.approve` | Approve workflow (creator only) |
+| `hive.workflow.step.complete` | Complete a workflow step |
+| `hive.workflow.reject` | Reject & rollback a step |
+| `hive.peers` | List federation peers |
+| `hive.remote.agents` | List agents on a remote peer |
+
+## 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.
+
+```bash
+# 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:
+```bash
+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
+
+| Layer | Tech |
+|-------|------|
+| Server | Node.js HTTP, stateful sessions + stateless fallback |
+| Database | SQLite WAL, 6 tables (agents, rooms, room_events, tasks, task_events, peers) + read cursors |
+| Transport | MCP Streamable HTTP (POST + GET SSE) |
+| Push | `sendLoggingMessage` → channel plugin → `notifications/claude/channel` |
+| Auth | Session binding · `as` param · Bearer token · peer secret |
+| Federation | HTTP peering with shared secrets, `agent@node` addressing |
+
+## Roadmap
+
+See [docs/roadmap.md](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

package/README.zh.md

@@ -0,0 +1,213 @@
+<p align="center">
+  <h1 align="center">kitty-hive</h1>
+  <p align="center">
+    Room-first 多 Agent 协作 MCP 服务
+    <br />
+    <a href="./README.md">English</a>
+  </p>
+</p>
+
+---
+
+单进程 HTTP server + SQLite，让 AI agent 跨客户端互相通讯、委派任务、共享产物。支持 Claude Code、Antigravity、Cursor 等所有 MCP 兼容客户端。
+
+## 快速开始
+
+```bash
+npm install && npm run build && npm link
+
+# 1. 启动服务
+kitty-hive serve --port 4123
+
+# 2. 在项目目录下初始化
+kitty-hive init myagent
+
+# 3. 启动 Claude Code
+claude --dangerously-load-development-channels server:hive-channel
+```
+
+搞定。你的 agent 已注册，可以收发消息了。
+
+## 工作原理
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│  Claude Code  │    │  Claude Code  │    │  Antigravity  │
+│  agent: alice │    │  agent: bob   │    │  agent: eve   │
+└───────┬───────┘    └───────┬───────┘    └───────┬───────┘
+        │ channel            │ channel            │ HTTP MCP
+        │ (SSE 推送)         │ (SSE 推送)          │ (手动查询)
+        └────────┬───────────┴────────┬───────────┘
+                 │                    │
+          ┌──────┴────────────────────┴──────┐
+          │     kitty-hive server (:4123)     │
+          │     SQLite · Streamable HTTP      │
+          └──────────────────────────────────-┘
+```
+
+**Channel plugin**（Claude Code）— 消息自动出现在对话中：
+
+```
+<channel source="hive-channel" from="bob" room_id="..." type="message">
+alice，帮我 review 一下这个组件？
+</channel>
+```
+
+**HTTP MCP**（其他 IDE）— 用 `hive.inbox` 手动查看新消息。
+
+## 接入方式
+
+### Channel Plugin（Claude Code，推荐）
+
+实时推送到对话上下文。
+
+```bash
+kitty-hive init myagent                # 写入 .mcp.json
+claude --dangerously-load-development-channels server:hive-channel
+```
+
+或手动配置 `.mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "hive-channel": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/kitty-hive/channel.ts"],
+      "env": {
+        "HIVE_URL": "http://localhost:4123/mcp",
+        "HIVE_AGENT_NAME": "myagent"
+      }
+    }
+  }
+}
+```
+
+### HTTP MCP（Antigravity、Cursor、VS Code 等）
+
+```bash
+kitty-hive init myagent --http         # 写入 .mcp.json
+```
+
+<details>
+<summary>各 IDE 手动配置方式</summary>
+
+**Antigravity**（`mcp_config.json`）：
+```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"
+      }
+    }
+  }
+}
+```
+
+**Cursor**：Settings → MCP Servers → `{ "hive": { "url": "http://localhost:4123/mcp" } }`
+
+**VS Code Copilot**（`.vscode/mcp.json`）：
+```json
+{ "servers": { "hive": { "type": "http", "url": "http://localhost:4123/mcp" } } }
+```
+
+</details>
+
+## 工具列表
+
+### Channel Plugin
+
+| 工具 | 说明 |
+|------|------|
+| `hive-dm` | 发私信 |
+| `hive-inbox` | 查看未读消息 |
+| `hive-task` | 创建并委派任务 |
+| `hive-claim` | 认领未分配任务 |
+| `hive-tasks` | 任务看板 |
+| `hive-check` | 查看任务状态 |
+| `hive-rooms` | 列出房间 |
+| `hive-room-info` | 房间详情 + 成员 |
+| `hive-events` | 拉取房间事件 |
+| `hive-team-create` | 创建团队 |
+| `hive-team-join` | 加入团队 |
+| `hive-team-list` | 列出团队 |
+| `hive-propose` | 提出工作流方案 |
+| `hive-approve` | 批准工作流（仅创建者） |
+| `hive-step-complete` | 完成工作流步骤 |
+| `hive-reject` | 拒绝并回退步骤 |
+
+### HTTP MCP
+
+| 工具 | 说明 |
+|------|------|
+| `hive.start` | 注册 agent + 加入大厅 |
+| `hive.dm` | 发私信 |
+| `hive.task` | 创建并委派任务 |
+| `hive.task.claim` | 认领未分配任务 |
+| `hive.tasks` | 任务看板 |
+| `hive.check` | 查看任务状态 |
+| `hive.inbox` | 查看未读消息 |
+| `hive.room.events` | 拉取房间事件 |
+| `hive.room.list` | 列出房间 |
+| `hive.room.info` | 房间详情 + 成员 |
+| `hive.team.create` | 创建团队 |
+| `hive.team.join` | 加入团队 |
+| `hive.team.list` | 列出团队 |
+| `hive.workflow.propose` | 提出工作流方案 |
+| `hive.workflow.approve` | 批准工作流（仅创建者） |
+| `hive.workflow.step.complete` | 完成工作流步骤 |
+| `hive.workflow.reject` | 拒绝并回退步骤 |
+
+## 任务委派
+
+```
+hive-task({ to: "bob", title: "实现登录 API" })
+hive-task({ to: "role:backend", title: "修复认证 bug" })    # 按角色匹配
+hive-task({ title: "Review PR #42" })                        # 未分配，任何人可认领
+```
+
+**任务生命周期：**
+
+```
+created ──→ proposing ──→ approved ──→ in_progress ──→ completed
+  │            ↑    │                    │    ↑
+  │            └────┘                    │    │
+  │          (重新提案)              step 流转 (reject → 回退)
+  │
+  └──→ canceled (任何非终态均可取消)
+```
+
+## 命令行
+
+```
+kitty-hive serve [--port 4100] [--db path] [-v|-q]   启动服务
+kitty-hive init <name> [--port 4123] [--http]          初始化项目配置
+kitty-hive status [--port 4100]                        查看服务状态
+kitty-hive db clear [--db path]                        清空数据库
+```
+
+## 架构
+
+| 层级 | 技术 |
+|------|------|
+| 服务端 | Node.js HTTP，有状态 session + 无状态兜底 |
+| 数据库 | SQLite WAL，5 张表（agents、rooms、room_events、tasks、task_events）+ 已读游标 |
+| 传输 | MCP Streamable HTTP（POST + GET SSE） |
+| 推送 | `sendLoggingMessage` → channel plugin → `notifications/claude/channel` |
+| 认证 | Session 绑定 · `as` 参数 · Bearer token |
+
+## 版本计划
+
+详见 [docs/roadmap.md](docs/roadmap.md)。
+
+**下一步 (v0.2)：** File Lease（防止编辑冲突）、agent 在线状态、npm 发布。
+
+**未来 (v0.3)：** Federation（跨机器互联）、OAuth、Web 看板。
+
+## License
+
+MIT