kitty-hive 0.5.2 → 0.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -31
- package/README.zh.md +46 -32
- package/channel.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -27,6 +27,8 @@ npx kitty-hive serve
|
|
|
27
27
|
claude --dangerously-load-development-channels plugin:kitty-hive@seangx
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
+
> **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.
|
|
31
|
+
|
|
30
32
|
On first use, ask the agent to call `hive-whoami(name=<your-name>)` to register.
|
|
31
33
|
Set `HIVE_AGENT_NAME=<name>` (or `HIVE_AGENT_ID=<id>`) in the env to skip this and auto-register on launch.
|
|
32
34
|
|
|
@@ -36,35 +38,44 @@ Set `HIVE_AGENT_NAME=<name>` (or `HIVE_AGENT_ID=<id>`) in the env to skip this a
|
|
|
36
38
|
# 1. Start server
|
|
37
39
|
npx kitty-hive serve
|
|
38
40
|
|
|
39
|
-
# 2. Write MCP config for your IDE (
|
|
41
|
+
# 2. Write MCP config for your IDE (cursor | vscode | antigravity | claude | all)
|
|
40
42
|
npx kitty-hive init cursor
|
|
41
43
|
```
|
|
42
44
|
|
|
43
45
|
## How It Works
|
|
44
46
|
|
|
47
|
+
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).
|
|
48
|
+
|
|
45
49
|
```
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
│
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
50
|
+
╔═════════════════════ your machine ═════════════════════╗ ╔══════ alice's machine ══════╗
|
|
51
|
+
║ ║ ║ ║
|
|
52
|
+
║ Claude Code Cursor Antigravity ║ ║ Claude Code ║
|
|
53
|
+
║ agent: bob-local agent: reviewer agent: worker ║ ║ agent: alice ║
|
|
54
|
+
║ │ │ │ ║ ║ │ ║
|
|
55
|
+
║ │ channel │ HTTP MCP │ HTTP MCP ║ ║ │ channel ║
|
|
56
|
+
║ │ (SSE push) │ (pull) │ (pull) ║ ║ │ ║
|
|
57
|
+
║ └────────┬───────┴────────┬───────┘ ║ ║ │ ║
|
|
58
|
+
║ ▼ ▼ ║ ║ ▼ ║
|
|
59
|
+
║ ┌────────────────────────────┐ ║ ║ ┌──────────────────┐ ║
|
|
60
|
+
║ │ kitty-hive serve (:4123) │ ◀────── peer ───────HTTP──▶│ kitty-hive :4123 │ ║
|
|
61
|
+
║ │ SQLite · Streamable HTTP │ (Bearer secret)║ │ │ ║
|
|
62
|
+
║ └────────────────────────────┘ ║ ║ └──────────────────┘ ║
|
|
63
|
+
╚════════════════════════════════════════════════════════╝ ╚═════════════════════════════╝
|
|
64
|
+
|
|
65
|
+
▲
|
|
66
|
+
│ peer (over Cloudflare tunnel or public IP)
|
|
67
|
+
▼
|
|
68
|
+
┌──────────────────────┐
|
|
69
|
+
│ carol's machine │ ... each hive is fully symmetric
|
|
70
|
+
│ kitty-hive :4123 │
|
|
71
|
+
└──────────────────────┘
|
|
63
72
|
```
|
|
64
73
|
|
|
65
|
-
**Claude Code** — Messages
|
|
74
|
+
**Claude Code** — Messages arrive automatically in your conversation via the channel plugin (SSE push).
|
|
75
|
+
|
|
76
|
+
**Other IDEs (Cursor / VS Code / Antigravity / …)** — Pull with `hive-inbox` when your agent wants to check.
|
|
66
77
|
|
|
67
|
-
**
|
|
78
|
+
**Cross-machine** — Peers connect symmetrically; no "primary" hive. See [Federation](#federation) for setup.
|
|
68
79
|
|
|
69
80
|
## Identity model
|
|
70
81
|
|
|
@@ -76,13 +87,14 @@ npx kitty-hive init cursor
|
|
|
76
87
|
|
|
77
88
|
## Tools
|
|
78
89
|
|
|
79
|
-
|
|
90
|
+
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.
|
|
80
91
|
|
|
81
92
|
### Identity
|
|
82
93
|
|
|
83
94
|
| Channel | HTTP | Description |
|
|
84
95
|
|---------|------|-------------|
|
|
85
|
-
| `hive-whoami` | `hive.whoami` | Show your agent id
|
|
96
|
+
| `hive-whoami` | `hive.whoami` | Show your agent id. **First use:** pass `name` to register (channel plugin transparently calls `hive.start` under the hood). |
|
|
97
|
+
| — | `hive.start` | Underlying registration RPC. HTTP/IDE users call this directly (channel users go via `hive-whoami`). |
|
|
86
98
|
| `hive-rename` | `hive.rename` | Change your global display_name |
|
|
87
99
|
| `hive-agents` | `hive.agents` | List all agents on the hive |
|
|
88
100
|
|
|
@@ -90,9 +102,10 @@ The channel plugin auto-mirrors HTTP server tools as kebab-case (`hive.team.crea
|
|
|
90
102
|
|
|
91
103
|
| Channel | HTTP | Description |
|
|
92
104
|
|---------|------|-------------|
|
|
93
|
-
| `hive-dm` | `hive.dm` | Send a direct message
|
|
94
|
-
| `hive-inbox` | `hive.inbox` | Check unread DMs / team / task events
|
|
95
|
-
| `hive-
|
|
105
|
+
| `hive-dm` | `hive.dm` | Send a direct message. Pass `attach: ["/abs/path"]` to send files/images (path on YOUR machine; receiver gets a `file_id` and fetches separately). |
|
|
106
|
+
| `hive-inbox` | `hive.inbox` | Check unread DMs / team / task events. Each DM entry carries `message_id` + `attachments` inline. |
|
|
107
|
+
| `hive-dm-read` | `hive.dm.read` | Fetch a single DM in full by `message_id` (use when a preview ends with `…(truncated; hive-dm-read message_id=N)`). |
|
|
108
|
+
| `hive-file-fetch` | `hive.file.fetch` | Fetch an attachment by `file_id`; optional `save_to` copies to a local path. |
|
|
96
109
|
|
|
97
110
|
### Teams
|
|
98
111
|
|
|
@@ -281,7 +294,7 @@ kitty-hive peer add marvin https://mac-tunnel.trycloudflare.com/mcp \
|
|
|
281
294
|
--secret <shared-secret> --expose <win-agent-id>
|
|
282
295
|
```
|
|
283
296
|
|
|
284
|
-
The first `add` may print `failed: HTTP 401` because the other side hasn't added you yet — that's fine; the next 60s heartbeat will flip both to `active`.
|
|
297
|
+
In this manual flow **both sides must paste the exact same `--secret`**. The first `add` may print `failed: HTTP 401` because the other side hasn't added you yet — that's fine; the next 60s heartbeat will flip both to `active`.
|
|
285
298
|
|
|
286
299
|
</details>
|
|
287
300
|
|
|
@@ -300,10 +313,10 @@ Replying to an incoming federated DM **does not** need `@peer` — your local pl
|
|
|
300
313
|
|
|
301
314
|
### Pitfalls
|
|
302
315
|
|
|
303
|
-
- `--expose` lists **the agent the
|
|
304
|
-
-
|
|
305
|
-
-
|
|
306
|
-
- Peer status
|
|
316
|
+
- `--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.)
|
|
317
|
+
- Agent ids are the safest value for `--expose`. Display names work only if globally unambiguous.
|
|
318
|
+
- "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>`.
|
|
319
|
+
- 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](#how-it-works-1) and `kitty-hive peer set-url` as manual recovery.
|
|
307
320
|
|
|
308
321
|
### How it works
|
|
309
322
|
|
|
@@ -334,6 +347,7 @@ kitty-hive peer add <name> <url> [--expose a,b] [--secret s] Add a peer manuall
|
|
|
334
347
|
kitty-hive peer list List peers
|
|
335
348
|
kitty-hive peer remove <name> Remove a peer
|
|
336
349
|
kitty-hive peer expose <name> --add/--remove <agent> Manage exposed agents
|
|
350
|
+
kitty-hive peer set-url <name> <url> Manually update a peer's URL (when auto-sync missed it)
|
|
337
351
|
kitty-hive config set <key> <value> Set config (e.g. name)
|
|
338
352
|
kitty-hive db clear [--db path] Clear the database
|
|
339
353
|
kitty-hive files clean [--days 7] Remove old federation transfer files
|
|
@@ -354,7 +368,7 @@ kitty-hive tunnel status [--port 4123] Show currently registere
|
|
|
354
368
|
| Layer | Tech |
|
|
355
369
|
|-------|------|
|
|
356
370
|
| Server | Node.js HTTP, stateful sessions + stateless fallback |
|
|
357
|
-
| Database | SQLite WAL — agents
|
|
371
|
+
| Database | SQLite WAL — `agents`, `teams`, `team_members`, `team_events`, `dm_messages` (with `attachments` JSON), `tasks` (with federation link fields), `task_events`, `read_cursors`, `peers`, `pending_invites`, `node_state` |
|
|
358
372
|
| Transport | MCP Streamable HTTP (POST + GET SSE) |
|
|
359
373
|
| Push | Channel plugin → `notifications/claude/channel`. Live SSE tracking; warns when push is dropped |
|
|
360
374
|
| Auth | Session binding · `as` param · Bearer token · peer secret |
|
package/README.zh.md
CHANGED
|
@@ -27,6 +27,8 @@ npx kitty-hive serve
|
|
|
27
27
|
claude --dangerously-load-development-channels plugin:kitty-hive@seangx
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
+
> **注意：** 目前**必须**带 `--dangerously-load-development-channels`，别被名字吓到删掉。Claude Code 的 `claude/channel` 能力还在 experimental，不加这个 flag，plugin 能装上但**收不到任何推送**。将来 CC 正式开放 channel 后可以去掉。
|
|
31
|
+
|
|
30
32
|
首次使用让 agent 调用 `hive-whoami(name=<你的名字>)` 注册。
|
|
31
33
|
也可以在环境变量里设 `HIVE_AGENT_NAME=<name>`（或 `HIVE_AGENT_ID=<id>`），channel 启动自动注册。
|
|
32
34
|
|
|
@@ -36,35 +38,44 @@ claude --dangerously-load-development-channels plugin:kitty-hive@seangx
|
|
|
36
38
|
# 1. 启动 server
|
|
37
39
|
npx kitty-hive serve
|
|
38
40
|
|
|
39
|
-
# 2. 写入 IDE 的 MCP
|
|
41
|
+
# 2. 写入 IDE 的 MCP 配置（cursor | vscode | antigravity | claude | all）
|
|
40
42
|
npx kitty-hive init cursor
|
|
41
43
|
```
|
|
42
44
|
|
|
43
45
|
## 工作原理
|
|
44
46
|
|
|
47
|
+
每台机器各自跑一个 `kitty-hive serve` —— **没有中心节点**。本地 agent 通过 MCP 连到自己这台 hive；hive 之间通过 HTTP 对等联邦（完全对称，没有主从）。
|
|
48
|
+
|
|
45
49
|
```
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
│
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
50
|
+
╔═════════════════════ 你的机器 ═════════════════════════╗ ╔══════ alice 的机器 ══════════╗
|
|
51
|
+
║ ║ ║ ║
|
|
52
|
+
║ Claude Code Cursor Antigravity ║ ║ Claude Code ║
|
|
53
|
+
║ agent: bob-local agent: reviewer agent: worker ║ ║ agent: alice ║
|
|
54
|
+
║ │ │ │ ║ ║ │ ║
|
|
55
|
+
║ │ channel │ HTTP MCP │ HTTP MCP ║ ║ │ channel ║
|
|
56
|
+
║ │ (SSE 推送) │ (拉取) │ (拉取) ║ ║ │ ║
|
|
57
|
+
║ └────────┬───────┴────────┬───────┘ ║ ║ │ ║
|
|
58
|
+
║ ▼ ▼ ║ ║ ▼ ║
|
|
59
|
+
║ ┌────────────────────────────┐ ║ ║ ┌──────────────────┐ ║
|
|
60
|
+
║ │ kitty-hive serve (:4123) │ ◀──── peer ───────HTTP─▶│ kitty-hive :4123 │ ║
|
|
61
|
+
║ │ SQLite · Streamable HTTP │ (Bearer 密钥) ║ ║ │ │ ║
|
|
62
|
+
║ └────────────────────────────┘ ║ ║ └──────────────────┘ ║
|
|
63
|
+
╚════════════════════════════════════════════════════════╝ ╚══════════════════════════════╝
|
|
64
|
+
|
|
65
|
+
▲
|
|
66
|
+
│ peer（走 Cloudflare tunnel 或公网 IP）
|
|
67
|
+
▼
|
|
68
|
+
┌──────────────────────┐
|
|
69
|
+
│ carol 的机器 │ ……每个 hive 完全对等
|
|
70
|
+
│ kitty-hive :4123 │
|
|
71
|
+
└──────────────────────┘
|
|
63
72
|
```
|
|
64
73
|
|
|
65
|
-
**Claude Code** — 消息以 `<channel>`
|
|
74
|
+
**Claude Code** — 消息以 `<channel>` 块自动出现在对话中（SSE 推送）。
|
|
75
|
+
|
|
76
|
+
**其他 IDE（Cursor / VS Code / Antigravity / …）** — agent 主动 `hive-inbox` 拉取。
|
|
66
77
|
|
|
67
|
-
|
|
78
|
+
**跨机器** — peer 是对称的，没有"主 hive"。配置见 [联邦](#联邦)。
|
|
68
79
|
|
|
69
80
|
## 身份模型
|
|
70
81
|
|
|
@@ -76,13 +87,14 @@ npx kitty-hive init cursor
|
|
|
76
87
|
|
|
77
88
|
## 工具
|
|
78
89
|
|
|
79
|
-
|
|
90
|
+
每个 HTTP 工具 `hive.foo.bar` 都被 channel plugin 镜像成 kebab-case `hive-foo-bar`。下表两列同一组工具，在 Claude Code 里用左列（channel），直接调 HTTP MCP 用右列。
|
|
80
91
|
|
|
81
92
|
### 身份
|
|
82
93
|
|
|
83
94
|
| Channel | HTTP | 说明 |
|
|
84
95
|
|---------|------|------|
|
|
85
|
-
| `hive-whoami` | `hive.whoami` | 查看自己 agent_id
|
|
96
|
+
| `hive-whoami` | `hive.whoami` | 查看自己 agent_id。**首次使用：** 传 `name` 注册（channel plugin 会透明地代理到 `hive.start`） |
|
|
97
|
+
| — | `hive.start` | 底层注册 RPC。HTTP/IDE 用户直接调用（channel 用户走 `hive-whoami`） |
|
|
86
98
|
| `hive-rename` | `hive.rename` | 改全局 display_name |
|
|
87
99
|
| `hive-agents` | `hive.agents` | 列出所有 agent |
|
|
88
100
|
|
|
@@ -90,9 +102,10 @@ Channel plugin 启动时自动从 server 抓取工具列表，把 `hive.team.cre
|
|
|
90
102
|
|
|
91
103
|
| Channel | HTTP | 说明 |
|
|
92
104
|
|---------|------|------|
|
|
93
|
-
| `hive-dm` | `hive.dm` |
|
|
94
|
-
| `hive-inbox` | `hive.inbox` | 查看未读 DM / team / task
|
|
95
|
-
| `hive-
|
|
105
|
+
| `hive-dm` | `hive.dm` | 发私信。传 `attach: ["/abs/path"]` 发文件/图片（路径是**你**这台机器的；对方拿到 `file_id` 另取） |
|
|
106
|
+
| `hive-inbox` | `hive.inbox` | 查看未读 DM / team / task 事件。每条 DM 带 `message_id` + `attachments` |
|
|
107
|
+
| `hive-dm-read` | `hive.dm.read` | 按 `message_id` 拉单条 DM 全文（preview 结尾 `…(truncated; hive-dm-read message_id=N)` 时用） |
|
|
108
|
+
| `hive-file-fetch` | `hive.file.fetch` | 按 `file_id` 取附件；`save_to` 可复制到指定位置 |
|
|
96
109
|
|
|
97
110
|
### 团队
|
|
98
111
|
|
|
@@ -100,7 +113,7 @@ Channel plugin 启动时自动从 server 抓取工具列表，把 `hive.team.cre
|
|
|
100
113
|
|---------|------|------|
|
|
101
114
|
| `hive-team-create` | `hive.team.create` | 创建团队（可设昵称） |
|
|
102
115
|
| `hive-team-join` | `hive.team.join` | 按名字或 id 加入团队 |
|
|
103
|
-
| `hive-team-list` | `hive.team.list` |
|
|
116
|
+
| `hive-team-list` | `hive.team.list` | 列出 hive 上所有团队 |
|
|
104
117
|
| `hive-teams` | `hive.teams` | 列出我所在的团队 |
|
|
105
118
|
| `hive-team-info` | `hive.team.info` | 团队成员 + 最近事件 |
|
|
106
119
|
| `hive-team-events` | `hive.team.events` | 增量拉取事件（`since`） |
|
|
@@ -280,7 +293,7 @@ kitty-hive peer add marvin https://mac-tunnel.trycloudflare.com/mcp \
|
|
|
280
293
|
--secret <共享密钥> --expose <win-agent-id>
|
|
281
294
|
```
|
|
282
295
|
|
|
283
|
-
|
|
296
|
+
这个手动流程里**双方必须粘贴一模一样的 `--secret`**。第一次 add 时另一边还没加你的 peer 记录，会显示 `failed: HTTP 401` —— 没事，下一次 60s 心跳两边都会转 `active`。
|
|
284
297
|
|
|
285
298
|
</details>
|
|
286
299
|
|
|
@@ -299,10 +312,10 @@ hive-check({ task_id: "<影子任务-id>" }) // 实时同步对面进度
|
|
|
299
312
|
|
|
300
313
|
### 避坑
|
|
301
314
|
|
|
302
|
-
- `--expose` 填的是**你这边、允许被对方联系的 agent
|
|
303
|
-
-
|
|
304
|
-
-
|
|
305
|
-
- peer status 只有 ping
|
|
315
|
+
- `--expose` 填的是**你这边、允许被对方联系的 agent**；不在列表里的对方完全看不到。**方向容易搞反。**
|
|
316
|
+
- 用 agent id 做 `--expose` 最稳；display_name 只在全局唯一时才能用。
|
|
317
|
+
- "节点名"（本机 `config set name` 设的、ping 响应里带的）和 "peer 名"（你本地 peer 记录的标签，初始跟对方节点名一样，但冲突时会自动加后缀）是两回事。跨机器寻址用 agent id + 本地 peer 名：`<agent-id>@<peer-name>`。
|
|
318
|
+
- peer `status` 只有 ping 成功往返才转 `active`。一直 `inactive` 多半是对方 URL 不可达，或者存的 tunnel URL 过期 —— 看下面 **Tunnel URL 自愈** 和 `kitty-hive peer set-url` 手动应急。
|
|
306
319
|
|
|
307
320
|
### 工作机制
|
|
308
321
|
|
|
@@ -333,6 +346,7 @@ kitty-hive peer add <name> <url> [--expose a,b] [--secret s] 手动加 peer
|
|
|
333
346
|
kitty-hive peer list 列出 peer
|
|
334
347
|
kitty-hive peer remove <name> 删除 peer
|
|
335
348
|
kitty-hive peer expose <name> --add/--remove <agent> 管理 peer 暴露的 agent
|
|
349
|
+
kitty-hive peer set-url <name> <url> 手动更新 peer 的 URL（自动同步漏掉时应急）
|
|
336
350
|
kitty-hive config set <key> <value> 设置配置（如 name）
|
|
337
351
|
kitty-hive db clear [--db path] 清空数据库
|
|
338
352
|
kitty-hive files clean [--days 7] 清理过期联邦传输文件
|
|
@@ -353,7 +367,7 @@ kitty-hive tunnel status [--port 4123] 查看当前注册的 tu
|
|
|
353
367
|
| 层级 | 技术 |
|
|
354
368
|
|------|------|
|
|
355
369
|
| 服务端 | Node.js HTTP，有状态 session + 无状态兜底 |
|
|
356
|
-
| 数据库 | SQLite WAL — agents
|
|
370
|
+
| 数据库 | SQLite WAL — `agents`、`teams`、`team_members`、`team_events`、`dm_messages`（含 `attachments` JSON）、`tasks`（含联邦字段）、`task_events`、`read_cursors`、`peers`、`pending_invites`、`node_state` |
|
|
357
371
|
| 传输 | MCP Streamable HTTP（POST + GET SSE） |
|
|
358
372
|
| 推送 | Channel plugin → `notifications/claude/channel`。跟踪活跃 SSE，丢包时打 warning |
|
|
359
373
|
| 认证 | Session 绑定 · `as` 参数 · Bearer token · peer secret |
|
package/channel.ts
CHANGED
|
@@ -105,7 +105,7 @@ async function registerAgent(opts: { id?: string; name?: string }) {
|
|
|
105
105
|
// --- MCP server (stdio, plugin-side) ---
|
|
106
106
|
|
|
107
107
|
const mcp = new Server(
|
|
108
|
-
{ name: 'hive-channel', version: '0.5.
|
|
108
|
+
{ name: 'hive-channel', version: '0.5.3' },
|
|
109
109
|
{
|
|
110
110
|
capabilities: { experimental: { 'claude/channel': {} }, tools: {} },
|
|
111
111
|
instructions: [
|