convez.ai
MCP ServerAutomaçãoAvançado
puxu-msft

Agent Neighbors

puxu-msft/agent-neighbors

Mensageria inter-sessão e coordenação entre agents Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que habilita mensageria cross-session entre múltiplas instâncias de Claude Code no mesmo projeto, com suporte a broadcast e ponto-a-ponto. Implementa injeção de hooks automática, despertar por eventos em ociosidade, locks colaborativos e sincronização entre agentes sem dependências externas.

Instalação

$npx convez-ai puxu-msft/agent-neighbors

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Coordenar múltiplas sessões de Claude Code trabalhando no mesmo repositório
  • Implementar locks colaborativos para evitar conflitos de edição simultânea
  • Disparar notificações e despertar sessões ociosas por eventos de outras sessões
  • Orquestração de tarefas distribuídas entre agents com sincronização em tempo real

Veredito

Ferramenta sofisticada e pronta para produção que resolve um problema real em workflows multi-agent complexos. Arquitetura bem pensada (zero dependências, single-file bundle, event-driven watcher) e documentação excelente compensam a curva de aprendizado. Recomendado para equipes que precisam orquestrar múltiplas sessões Claude Code no mesmo projeto.

README

A tradução para o português deste README ainda está na fila.

neighbors

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

特性:广播 + 点对点 · 事件驱动自主投递(钩子注入,无需用户转述)· 可读别名与任务简述(含新鲜度)· reply_to 线程化 · 目录 GC · 可配作用域/续跑上限/广播限频 · idle 唤醒(事件驱动 watcher,默认开,可关)· 零依赖自包含 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看在线邻居及其当前任务(含状态时间,如 06-15 14:32:07)
send发消息:to="broadcast"(广播)或别名(点对点);回复某条消息时填 reply_to=对方 #编号;expects_reply: true 表示期待回应(配合 watcher 等应答唤醒)
status更新你正在做什么(任务转向/完成时诚实更新)
read手动看广播 + 自己信箱历史(每条标 #编号、年龄、↩#回复号)
lock认领/释放资源区段(路径前缀,advisory 协作锁):op="acquire" 认领(wait: true 被占时返回等待武装指令,仅返回 ✅ 才算持有);op="release" 释放(仅持有者可)。acquire/release 同一授权单元
lock_list(只读)列出当前所有活动区段锁及持有者

idle 唤醒(守望,默认开)

默认会话被引导在空闲(等待用户输入)时也能收到邻居消息:会话以后台任务武装一个事件驱动 watcher(scripts/watcher-run.mjs),阻塞监听本会话未读(fs.watch 盯 inbox/new+broadcast),有新消息即退出 → Claude Code 的 task-notification 唤醒该 idle 会话 → 现有钩子投递消息内容。

  • 职责分离:唤醒走"后台任务完成→task-notification",内容仍走现有 PostToolUse/Stop 投递;watcher 只"叫醒"、不搬运内容。
  • 武装/re-arm:SessionStart 首次武装;活动期 PostToolUse 在 watcher 未存活时节流提醒(默认 5 分钟一次);每次被唤醒后由 watcher 输出引导重启。.watch/<sid>.pid 单例防重复武装。
  • 降级:re-arm 依赖会话主动重启 watcher,偶有遗漏 = 优雅退回原状(消息不丢,下次活动照常投递)。是 best-effort 的一声"叮",非保证送达。
  • 关闭:设 IDLE_WATCH=0。

资源区段锁与同步请求(协作避让,advisory)

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

  • 区段锁:lock(op="acquire", resource="src/auth/", from="<别名>") 认领前缀(含子区段冲突)。被占且 wait: true 时返回武装指令——以 run_in_background 跑你的 watcher 命令并追加 --lock-free "src/auth/",被唤醒后必须再 lock(op="acquire", …) 确认 ✅ 才可进入(唤醒只表示"可再试"、你尚未持有)。完成即 lock(op="release", …)。advisory:靠协作自律,非强制隔离。
  • 租约(免手动续期):持有者活动期心跳自动续约;持有者崩溃(DEAD)或长时间无活动(超 LOCK_HOLD_TTL)→ 锁视同遗弃可被回收。
  • 同步请求:send(..., expects_reply: true) 后按返回指令追加 --reply-to <id> 武装等应答的 watcher;应答到达 / 超时 / 对端下线时被唤醒。
  • 心跳三态:会话存活分 ENGAGED(近期活动)/ AMBIGUOUS(在但空闲)/ DEAD(进程没了),驱动锁回收与请求早退。天花板:心跳证进程存活,非"循环在推进"(空闲≡卡死,进程层同态)。
  • 承重原语经实测:锁获取(wx)与偷锁(捕获-rename)经并发 POC 验证(exp/lock-poc/);仅本地 POSIX FS(非 NFS/WSL DrvFs)保证原子性。

手动命令与协作 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/(含心跳 beat_ts/state)、.cursors/、locks/(区段锁)。建议加入 .gitignore。

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

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

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

配置(可选)

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

键类型默认作用
CONTINUATION_CAP数字0=不限无用户介入时 Stop 连续自动续跑上限。N>0 则每 N 跳停下交还用户,防 ping-pong 烧 token;未读留待下次活动投递(不丢)。
SCOPE字符串worktreerepo 让同一 git 仓库的所有 worktree 共享一个 neighbors 空间(需各参与 worktree 都设 repo,混合作用域只部分互通)。
BROADCAST_MIN_INTERVAL数字秒0=不限同一会话两次广播的最小间隔。N>0 时过频广播被拒(提示等待),防刷屏;点对点不受此限。协作自律(from 自报,非对抗防御)。
MESSAGE_MAX_CHARS数字0=不限单条消息 body 字符上限。N>0 时超长被拒,防巨型消息注入每个收件人上下文。
STATUS_MAX_CHARS数字0=不限状态 text 字符上限(状态注入每个邻居的 list)。N>0 时超长被拒。
IDLE_WATCH开关开idle 唤醒能力开关(见上「idle 唤醒」)。设 0/false/off 关闭。注:这是能力开关、默认开,与上面"限制类默认 0=关"的约定不同。
IDLE_WATCH_TIMEOUT数字秒0=不超时watcher 自退出超时。0=纯事件驱动(默认);N>0 时每 N 秒退出一次作保活脉冲(空唤醒一次→re-arm),用于规避后台任务可能的时长上限。
HEARTBEAT_TTL数字秒30心跳新鲜窗口(liveness 类,强制非 0):beat 在此窗口内 = ENGAGED。默认容长工具调用。
LOCK_HOLD_TTL数字秒1800锁租约窗口:持有者超此秒数无活动(beat 未刷)→ 锁视同遗弃可回收。
LOCK_WAIT_TIMEOUT数字秒120等锁的兜底唤醒超时(liveness 类,强制非 0),独立于锁租约。
REQUEST_DEFAULT_TIMEOUT数字秒300等应答的兜底唤醒超时(liveness 类,强制非 0)。
MAX_TRANSIENT_WATCHERS数字4每会话并存的临时 watcher(等锁/等应答)上限。

重要约束

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

Bom para

Relacionados