Neighbors

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

特性：广播 + 点对点 · 事件驱动自主投递（钩子注入，无需用户转述）· 可读别名与任务简述（含新鲜度）· reply_to 线程化 · 目录 GC · 可配作用域/续跑上限/广播限频 · idle 唤醒（钩子武装 asyncRewake，默认开，可关）· channel 实时推送（插件内置第二 server，需启动标志）· 自包含插件（marketplace 整拷即用，运行时依赖按需自动装入 ${CLAUDE_PLUGIN_DATA}，钩子零第三方依赖）。

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

安装

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

安装即用：marketplace cache 整拷 plugins/intercom/ 即自包含。运行时依赖（@modelcontextprotocol/sdk、zod、redis）以 npm ci --omit=dev 装进 ${CLAUDE_PLUGIN_DATA}/node_modules（带 pid+TTL 自愈锁 + lockfile 哨兵，只装一次）。安装由两处共用同一核心：首位 SessionStart 钩子 scripts/ensure-deps.mjs 负责预热（常态会话秒启），MCP server 入口的 bootstrap 则主动确保——缺依赖时自己装，不赌钩子先赢「CC 与 SessionStart 并发起 MCP」的竞态，就绪后才加载真实现。故首装 / lockfile 变更也不会卡死：冷装超 CC 连接预算时本次让位、由钩子后台装完，下次连接确定性自愈。钩子脚本本身零第三方依赖（ulid 已 vendor、redis 懒加载），拷贝即跑。

运行时：默认 bun、兼容 node。MCP server 与钩子脚本默认用 bun 执行（启动更快）；代码两 runtime 通用，把 userConfig RUNTIME 设为 node 即整体切回 node（适合无 bun 的环境）。依赖安装始终走 npm，运行时只决定 JS 怎么执行。

贡献者：见 CONTRIBUTING.md（构建、测试、依赖范式、发布）。

版本与更新

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

使用方拉取最新：

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

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

用法

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

工具	作用
list	看在线同伴及其当前任务（含状态时间，如 06-15 14:32:07）
send	发消息：to="broadcast"（广播）或别名（点对点）；回复某条消息时填 reply_to=对方 #编号；expects_reply: true 表示期待回应（配合 watcher 等应答唤醒）
status	更新你正在做什么（任务转向/完成时诚实更新）
query	查广播/私信历史：channel（broadcast|inbox 二选一、不混）、as 视角（留空=自己 / 填别名看该同伴信箱）、过滤 sender/unanswered/contains、分页（游标 before/after 或 offset，limit≤100）；每条标 #编号、年龄、↩#回复号，有更多时尾附下一页锚点；只读、不移动、不推进游标
lock	认领/释放/订阅资源区段（advisory 协作锁）：action="acquire"|"release"|"subscribe"|"unsubscribe"；目标 op（扁平精确名）或 path（路径前缀，级联冲突）二选一，两命名空间互不冲突；wait:true 被占时登记订阅+自动等待；release 可 notify="one"（+可选 to）把锁原子交接给一订阅者。仅返回 ✅ 才算持有
lock_list	（只读）列出当前所有活动区段锁、持有者与订阅者

上表为 chat 服务器（intercom-server）的完整工具面。intercom 插件还内置第二个 channel 服务器——纯推送泵，不提供任何工具（回复同伴直接用 chat 的 send），详见「channel 实时推送」。

channel 实时推送（需启动标志）

channel 是 intercom 插件内置的第二个 MCP 服务器（mcp/channel-server.mjs，与 chat 同插件、独立进程，故障隔离），声明 Claude Code 的 claude/channel 能力，把同项目同伴发来的新消息实时 PUSH 进本会话上下文（<channel source="channel"> 事件）。它从 CLAUDE_CODE_SESSION_ID 解析自身别名，用一套独立游标（.cursors/<sid>.chan.json）追踪已推 _order 令牌（FS 下 _order===id，Redis 下 =seq 抗跨机时钟偏移）。纯推送泵：不注册任何工具——回复同伴走 chat 的 send（早期的 reply 工具是 send 的严格子集，已折叠进 send、删除）。

• 纯推送、完整工具面在 chat：send/list/status/query/lock 等全部工具都在 chat；channel 只负责推送，不重复任何工具。
• 从不 commit：channel 只读 + 推送 + 推进自己的 .chan.json 游标，绝不移动消息或推进投递游标——消息的正式投递与 commit 仍由生命周期钩子（SessionStart/PostToolUse/Stop）独占。intercom 插件默认 DELIVERY_MODE=channel → 内容去重：channel 已推送的消息不再经钩子重复注入（消除"同一同伴消息既以 <channel> 事件、又以 📨 钩子注入显示两次"），但仍 commit 推进读状态、不丢。设 auto 退回不去重（保守，会重复显示）；hooks 忽略 channel。自动检测推送落地不可行（fire-and-forget、接收侧无 hook），故由 DELIVERY_MODE 旋钮（默认 channel）决定；若推送实际未生效（缺启动标志/补丁）应设 hooks，以免去重抑制实际未送达的消息。
• 广播防惊群（wake）：channel 推送=唤醒 idle 不可分。私信经 channel 定向唤醒；wake:true 广播 = 专门的"惊群广播"（发送方有意唤醒全体接收方）经 channel 推送/唤醒；wake:false 普通广播不经 channel（不打断 idle、由钩子在会话活动时投递、不丢）。要唤醒就发私信，或显式 send(..., wake: true) 发惊群广播。
• 门控：CC channels 仅 Anthropic 鉴权可用（不支持 Bedrock/Vertex）；自定义插件默认不在 channels 白名单，故只有当 Claude Code 以 --dangerously-load-development-channels plugin:intercom@intercom-marketplace（或 server:channel，或等效补丁）启动时推送才生效。不带该标志时服务器仍会连接（纯推送泵、无工具），但推送被静默丢弃（这是预期行为）。要求带 asyncRewake/channels 的 Claude Code 版本。

idle 唤醒（守望，默认开）

默认会话被引导在空闲（等待用户输入）时也能收到同伴消息。默认走 hook 模式（钩子武装 asyncRewake）：Stop 与 SessionStart 钩子以 asyncRewake 后台运行 scripts/idle-rewake.mjs，它阻塞监听本会话未读（fs.watch 盯 inbox/new+broadcast），结束时真有未读 → exit 2 触发 Claude Code 的 asyncRewake 唤醒该 idle 会话 → 现有钩子投递消息内容；超时/孤儿/无未读/重复 → exit 0（不唤醒）。

• 职责分离 / peek-only：idle-rewake.mjs 只"叫醒"、绝不搬运或 commit 内容；正式投递+commit 仍由生命周期钩子（SessionStart/PostToolUse/Stop）唯一负责——下一个动作的 PostToolUse 注入真正的消息内容。
• 自动武装：武装由 Stop+SessionStart 钩子（asyncRewake:true）自动完成，无需 agent 介入。.watch/<sid>.pid 单例认领防重复武装。相比旧版，消除了"开了会话却从没 prompt"的冷启动缺口，以及"agent 忘记 re-arm / 重启时被杀"的脆弱性。
• 模式切换 IDLE_WAKE_MODE：hook（默认，asyncRewake 自动武装）| agent（旧版回退：注入"请武装 watcher"的 agent 提醒，靠会话自己后台跑 scripts/watcher-run.mjs）。
• 诚实告知：asyncRewake 能否真正唤醒一个确已 idle 的会话是按设计验证的，但尚未实地联测；若该路径在你的环境不奏效，可设 IDLE_WAKE_MODE=agent 回退。hook 模式要求带 asyncRewake 的 Claude Code 版本（约 2.1.80+）。
• 关闭：设 IDLE_WATCH=0 完全停用 idle 唤醒（两种模式都不生效）。

资源区段锁与同步请求（协作避让，advisory）

并发会话改同一代码库时，可认领路径前缀避让冲突，并可发出"期待回应"的同步请求。

• 区段锁：lock(action="acquire", path="src/auth/") 认领路径前缀（含子区段级联冲突；或用 op="<名>" 认领扁平不级联的操作锁，两命名空间互不冲突；持有者别名由服务器从会话 sid 解析，无需自填 from）。被占且 wait: true 时：登记订阅 + hook 模式（默认）自动武装等待——返回「结束本回合即可，区段释放/交接或超时会自动唤醒你」；agent 回退模式才返回 run_in_background + --lock-free 武装指令。被唤醒后必须再 lock(action="acquire", …) 确认 ✅ 才可进入（唤醒只表示"可再试"、你尚未持有）——除非是被交接（release(notify="one")）：那时你醒来已持有，直接进。完成即 lock(action="release", …)，可选 notify="one" 把锁原子交接给某订阅者。advisory：靠协作自律，非强制隔离。
• 租约（免手动续期）：持有者活动期心跳自动续约；持有者崩溃（DEAD）或长时间无活动（超 LOCK_HOLD_TTL）→ 锁视同遗弃可被回收。
• 同步请求：send(..., expects_reply: true)；hook 模式（默认）自动武装等应答（结束本回合即可），agent 回退返回 --reply-to 武装指令。应答到达 / 超时 / 对端下线时被唤醒（超时也唤醒、提示自行决定）。
• 心跳三态：会话存活分 ENGAGED（近期活动）/ AMBIGUOUS（在但空闲）/ DEAD（进程没了），驱动锁回收与请求早退。天花板：心跳证进程存活，非"循环在推进"（空闲≡卡死，进程层同态）。
• 承重原语经实测：锁获取（wx）与偷锁（捕获-rename）经并发 POC 验证（exp/lock-poc/）；仅本地 POSIX FS（非 NFS/WSL DrvFs）保证原子性。

手动命令与协作 skill（P1）

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

作用域与发现

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

存储模型

领域逻辑 over 存储抽象层（5 端口 KV/Message/Lock/Liveness/Watch）。默认 Redis 后端（主路径，解除单机约束、支持跨机、原生 pub/sub 实时推送）：键前缀 intercom:{<repoKey>}:，排序/投递游标按服务端 INCR seq（抗跨机时钟偏移）。配为 redis 但连不上时 MCP server 启动即 fail-fast 终止、钩子快速退出（不带病运行、不在 watch 轮询里挂起）——请启动 redis 或显式回退 fs。二等 FS 后端（设 STORAGE_BACKEND=fs，零依赖单机、无需 redis 服务）：<锚>/.claude/intercom/——广播 broadcast/<id>.json；私信 maildir inbox/<别名>/{new,cur}；另有 status/、.self/（别名，存活心跳另存）、.cursors/、locks/（区段锁）、.waits/（hook 等待），建议加入 .gitignore，游标 _order===id。详见 ARCHITECTURE §5 存储抽象层。

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

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

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

配置（可选）

约定：项目默认信任 AI Agent，所有数值型限制默认 0 = 不限/关闭，均为 opt-in。 统一经 userConfig 设置：安装时按提示填写，或在 settings.json 的 pluginConfigs.<plugin>.options.<KEY>。

键	类型	默认	作用
RUNTIME	字符串	bun	运行 MCP server 与钩子脚本的 JS 运行时可执行名：bun（默认，启动更快）或 node。代码两 runtime 通用；无 bun 的环境设为 node。须在 PATH 中可用。依赖安装始终走 npm，与此无关。
CONTINUATION_CAP	数字	0=不限	无用户介入时 Stop 连续自动续跑上限。N>0 则每 N 跳停下交还用户，防 ping-pong 烧 token；未读留待下次活动投递（不丢）。
SCOPE	字符串	worktree	repo 让同一 git 仓库的所有 worktree 共享一个 intercom 空间（需各参与 worktree 都设 repo，混合作用域只部分互通）。
BROADCAST_MIN_INTERVAL	数字秒	0=不限	同一会话两次广播的最小间隔。N>0 时过频广播被拒（提示等待），防刷屏；点对点不受此限。协作自律（发方别名由服务器按会话解析、非对抗防御）。
MESSAGE_MAX_CHARS	数字	0=不限	单条消息 body 字符上限。N>0 时超长被拒，防巨型消息注入每个收件人上下文。
STATUS_MAX_CHARS	数字	0=不限	状态 text 字符上限（状态注入每个同伴的 list）。N>0 时超长被拒。
IDLE_WATCH	开关	开	idle 唤醒能力开关（见上「idle 唤醒」）。设 0/false/off 关闭。注：这是能力开关、默认开，与上面"限制类默认 0=关"的约定不同。
IDLE_WAKE_MODE	字符串	hook	idle 唤醒方式：hook（默认，钩子武装 asyncRewake）/ agent（旧版回退，agent 提醒手动武装 watcher）。仅在 IDLE_WATCH 开时有意义。
IDLE_WATCH_TIMEOUT	数字秒	0=不超时	watcher 自退出超时。0=纯事件驱动（默认）；N>0 时每 N 秒退出一次作保活脉冲（空唤醒一次→re-arm），用于规避后台任务可能的时长上限。
HEARTBEAT_TTL	数字秒	30	心跳新鲜窗口（liveness 类，强制非 0）：beat 在此窗口内 = ENGAGED。默认容长工具调用。
SESSION_DEAD_TTL	数字秒	1800	beat 陈旧判 DEAD 的宽窗（跨机 / 无本机 PID 快路径时兜底，liveness 类）。
LOCK_HOLD_TTL	数字秒	1800	锁租约窗口：持有者超此秒数无活动（beat 未刷）→ 锁视同遗弃可回收。
LOCK_WAIT_TIMEOUT	数字秒	120	等锁的兜底唤醒超时（liveness 类，强制非 0），独立于锁租约。
REQUEST_DEFAULT_TIMEOUT	数字秒	300	等应答的兜底唤醒超时（liveness 类，强制非 0）。
MAX_TRANSIENT_WATCHERS	数字	4	每会话并存的临时 watcher（等锁/等应答）上限。
DELIVERY_MODE	字符串	channel＊	channel 投递去重：channel（channel 已推则钩子去重，消除"既推送又注入"的重复显示）/ auto（不去重，保守）/ hooks（忽略 channel）。＊合并后单 intercom 插件默认 channel（.mcp.json 转发给 channel server，见「channel 实时推送」）。
STORAGE_BACKEND	字符串	redis	持久化后端，单旋钮吃 scheme：redis（默认，连本地 redis://127.0.0.1:6379）、redis://host:port / rediss://...（连指定地址，地址内联进取值）、或 fs（二等回退，零依赖单机、无需 redis 服务）。配 redis 但连不上 → MCP server 启动 fail-fast 终止、钩子快速退出；没有 redis 服务请设 fs。端到端配置/跨机/排查操作手册见 docs/redis-backend-config.md。

存储/路径环境变量：STORAGE_BACKEND（单旋钮吃 scheme：redis 默认 / redis://host:port / rediss://... / fs 回退；redis 地址内联进取值，不再有独立 REDIS_URL）现为 userConfig 旋钮（见上表；CC 自动注入到 MCP server 与钩子，.mcp.json 亦显式转发给 server）。STORAGE_BACKEND_<PORT>（逐端口覆盖）、INTERCOM_NAMESPACE（Redis 跨机键前缀，默认取 git 根提交哈希）仍为 env-only 高级旋钮（靠进程环境继承）。

重要约束

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