neighbors

让同一 neighbors 作用域内的多个 Claude Code 会话互相发消息（广播 + 点对点），并在会话进行中自主投递。

特性：广播 + 点对点 · 事件驱动自主投递（钩子注入，无需用户转述）· 可读别名与任务简述（含新鲜度）· reply_to 线程化 · 目录 GC · 可配作用域/续跑上限/广播限频 · 零依赖自包含 bundle。

当前架构见 docs/ARCHITECTURE.md；演进史见 CHANGELOG.md；文档索引 docs/。

安装

/plugin marketplace add <本仓库 URL 或本地路径>
/plugin install neighbors@neighbors-marketplace

零配置：MCP 服务器已打包为自包含单文件 mcp/neighbors-server.bundle.mjs（内联 SDK/zod/lib），运行时无需 npm install、无需 node_modules；钩子脚本本就零依赖。

贡献者：见 CONTRIBUTING.md（构建、测试、bundle、发布）。

版本与更新

本插件不固定 version 字段（plugin.json / marketplace.json 均不写 version）。源仓库是 git 仓库，Claude Code 按解析规则回退到 commit SHA 当版本——每次提交即一个新版本，无需手动 bump（这正是官方对"内部/快速迭代插件"的推荐做法）。发布 = 提交即可。

使用方拉取最新：

/plugin marketplace update neighbors-marketplace
/plugin update neighbors            # 然后新开会话让新 hooks/MCP 生效

注：package.json 仍带 version，仅为 npm/开发元数据，与插件版本解析无关。若哪天 /plugin update 显示版本为 unknown（而非 SHA），说明该 marketplace 未被当 git 源——届时改回在 plugin.json 写显式 semver 并每次 bump。

用法

• 每会话启动自动获别名（如 amber-fox），并被告知可用工具。
• 收到的消息会在工作过程中自动注入；有未读时会话不会停下，直至对话平静。

工具	作用
list	看在线邻居及其当前任务（含状态新鲜度，如「5 分钟前」）
send	发消息：to="broadcast"（广播）或别名（点对点）；回复某条消息时填 reply_to=对方 #编号
status	更新你正在做什么（任务转向/完成时诚实更新）
read	手动看广播 + 自己信箱历史（每条标 #编号、年龄、↩#回复号）

手动命令与协作 skill（P1）

• /neighbors:neighbors <自然语言> —— 手动查看/发消息/更新状态/读历史（如 /neighbors:neighbors send jade-owl 帮我看下 auth）。
• neighbors-coordination skill —— 多会话协作时自动加载，引导主动报状态、查重、协调；独立任务不触发。

作用域与发现

• 作用域：默认在 git 仓库内，从 git 根向当前目录找到的第一个 .claude 即锚点（同一工作树的子目录共享）；非 git 仓库用项目目录。两个会话"互为邻居"当且仅当解析出的 neighbors 目录相同。同一仓库的不同 worktree 默认彼此隔离——要让它们互通，把 SCOPE 设为 repo（见「配置（可选）」）。
• 在线发现：读取 ~/.claude/sessions/<pid>.json 进程注册表（pid 验活）。该文件为 Claude Code 内部、未文档化、随版本可能变化；本插件不追求强跨版本兼容。就地格式变更会被探测：若注册表里有会话文件却无一可识别，list 会给出"在线发现可能已失效，请更新插件"的降级提示（整目录被移走/改名则无法探测，按"无人"处理）。无论如何，消息收发只依赖 .claude/neighbors/ 文件，不受发现失效影响。

存储模型

<锚>/.claude/neighbors/：广播 broadcast/<id>.json；私信 maildir inbox/<别名>/{new,cur}；另有 status/、.self/、.cursors/。建议加入 .gitignore。

会话启动时惰性 GC（best-effort）：广播按"所有活跃会话都已读"的水位线清理（绝不删未读）；已读私信 cur/ 按 7 天保留期清理。私信未读（new/）永不被清。

惰性创建：会话只在实际写入时创建文件/目录；只启动不收发、不设状态的会话仅登记 .self/<sid>.json（如有历史广播再加一个游标），不留占位文件。

死会话清理：会话进程死亡且逾 30 天无任何启动时，其残留元数据（.self/游标/状态/信箱）在他人 SessionStart 时被清；活会话、当前会话、近期会话与被复用的别名均受保护。

配置（可选）

• CONTINUATION_CAP（数字，默认 0=不限）：无用户介入时 Stop 连续自动续跑的上限。设为 N>0 时，每 N 跳插入一次停下交还用户，防 ping-pong 烧 token；未读消息留待下次活动投递，不丢。安装时按提示填写，或在 settings.json 的 pluginConfigs.<plugin>.options.CONTINUATION_CAP。
• SCOPE（字符串，默认 worktree）：worktree 按当前工作树/目录锚定；repo 让同一 git 仓库的所有 worktree 共享一个 neighbors 空间。注意：跨 worktree 互通需每个参与 worktree 的会话都设为 repo（混合作用域只部分互通）。
• BROADCAST_MIN_INTERVAL（数字秒，默认 0=不限）：同一会话两次广播的最小间隔。设为 N>0 时，过于频繁的广播被拒（提示等待），防多会话刷屏；点对点不受此限。默认无限制。属协作场景的自律限制（from 自报，非对抗防御）。

重要约束

• .claude/neighbors/ 与 ~/.claude/sessions/ 须位于 Linux 原生文件系统（WSL 勿放 /mnt/c）。
• 自主续跑默认无人为上限：两个被指令驱使的会话可能持续互回（ping-pong）。可设 CONTINUATION_CAP 限制，或随时按 Esc 中断。