claude-bulkhead
让多个 Claude Code 会话共机时不互相踩脚:按会话归属拦截误杀进程、抢端口和 git add -A,并给出安全替代命令。
- Star 数
- ★ 35
- 最近更新
- 今天
- License
- MIT
- 主语言
- JavaScript
- FA 评分
- 78/100 · 表现良好
30 秒速览
- 可在哪里用
- 兼容但需适配Codex · Claude Code
- 开始前需要
- 典型场景
- 在一台机器上用多个 git worktree 并行运行 Claude Code 会话,担心一个会话 pkill node 打掉别人的 dev server 的开发者。
- 主要局限
- 只分析命令文本,对包裹在脚本文件、shell 函数或别名里的 kill、sleep 不可见,属于尽力而为而非强制隔离。
- 维护状态
- 近 30 天有提交最近提交 2026-11-20最新版本 v0.5.2(2026-11-20)
- 源码审查
- 78/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
claude-bulkhead 是一组无依赖的 Node 脚本形式的 Claude Code hooks,在每次 Bash、PowerShell、Read、Edit 调用前运行。它读取命令文本,仅在命令匹配时才进一步查询进程表、监听端口、~/.claude/sessions 中的会话记录、空闲内存和 git 状态,判断该操作是否会伤到同机其它会话或子代理。需要拦截时以退出码 2 加说明消息阻止命令,并告诉 Claude 应改用的安全命令;内部出错则放行。它同时可加载到 Codex、Gemini CLI、Copilot CLI、Cursor、opencode 等十余种编码代理,支持 Windows、Linux、macOS,无网络调用、无后台守护进程。
安装后提供 kill-guard、port-guard、memory-guard、checkout-guard、disk-guard、wait-guard、basics、edit-guard、secrets-guard(默认关闭)与 orphan-reaper 等守卫,每个都是独立 Node 脚本,可单独用 BULKHEAD_DISABLE 关闭。kill-guard 拦截 pkill、killall、taskkill /IM、Stop-Process -Name 等按程序名的大范围杀进程;port-guard 拦截在另一会话已占用端口上启动 dev server 或按端口杀进程;memory-guard 在可用内存过低时拦截重型构建与测试,配合 bulkhead-slot 把任务按共享内存预算排队;checkout-guard 在同一 git 树里还有活跃会话时拦截 checkout、stash、reset --hard、git add -A、删除他人目录;disk-guard 拦截全盘 du/find 与并行扫描;wait-guard 拦截超过 180 秒的前台 sleep 循环;orphan-reaper 在会话退出后清理遗留的 dev server、测试 worker、watcher 和无头浏览器。CLI 端提供 bulkhead status/top/log/doctor/scan/worktree/remote/allow/explain 等命令,events.jsonl 记录每次拦截,bulkhead-statusline 输出状态行。
- 在一台机器上用多个 git worktree 并行运行 Claude Code 会话,担心一个会话 pkill node 打掉别人的 dev server 的开发者。
- 多个会话共享同一 checkout,需要防止 git add -A 把别的会话未完成的改动裹进自己提交的团队。
- 在同一台机器上同时跑 Claude Code 和 Codex、Gemini CLI、Cursor 等多个编码代理,希望统一护栏的人。
- 经常让子代理跑 Playwright、next build、测试套件,机器内存被打爆的工程师,可用 memory-guard 与 bulkhead-slot 排队。
- 想先评估风险再决定是否采用:可用 /bulkhead:scan 30d 回放历史 transcript,统计过去一个月会被拦下多少条命令。
- 希望在会话退出后自动回收遗留开发服务器和测试进程、避免端口与内存被长期占用的用户。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
npm install -g claude-bulkheadnpx claude-bulkhead top
- 配置文件
~/.cursor/plugins/local/bulkhead~/.claude/bulkhead/config.json.claude/bulkhead.json.env- 运行环境
- Node.js 18
- 安装说明涉及
- Windows
如何安装或部署这个 Agent?
需要在 PATH 上有 Node 18 或更高版本(用 node --version 检查)。在 Claude Code 内添加 marketplace 并安装插件:
/plugin marketplace add dooly6276/claude-bulkhead
/plugin install bulkhead@bulkhead可选的全局 npm 安装,用于终端命令、状态行、bulkhead-slot 和其它代理的 setup:
npm install -g claude-bulkhead其它代理可加载同一套守卫,例如:
copilot plugin marketplace add dooly6276/claude-bulkheadgit clone https://github.com/dooly6276/claude-bulkhead ~/.cursor/plugins/local/bulkheadgemini extensions install https://github.com/dooly6276/claude-bulkheadcodex plugin marketplace add dooly6276/claude-bulkhead
codex plugin add bulkhead@bulkhead如何使用这个 Agent?
装好后守卫在每次 Bash、PowerShell、Read、Edit 调用时自动运行,无需额外操作。先回放历史记录看会拦下什么(只读、不上传):
/bulkhead:scan 30d检查安装与拦截是否生效:
/bulkhead:doctor在另一个终端查看实时会话、内存与端口:
npx claude-bulkhead top查看拦截记录与放行被误拦的命令(allow 只能由用户本人执行,代理无法自行批准):
bulkhead log --summary --since 7d
bulkhead allow 7F3K调整阈值写在全局配置 ~/.claude/bulkhead/config.json,项目内 .claude/bulkhead.json 只能加严:
{
"killGuard": { "allowNames": ["ffmpeg"] },
"waitGuard": { "limitSeconds": 300 },
"portGuard": { "ignorePorts": [9229] }
}一步创建工作树(复制 .env、安装依赖、分配稳定端口):
bulkhead worktree add fix-login这个 Agent 有哪些优点和局限?
- 按会话归属判定而非简单黑名单:只有当另一个活跃会话真正受牵连时才拦截,并在消息里给出可执行的安全替代命令。
- 零依赖、无守护进程、无遥测、无网络调用,除 bulkhead remote 走用户配置的 SSH 外数据不出本机,日志只落在状态目录。
- bulkhead scan 可先回放历史 transcript 量化收益,再决定是否采用,且输出会自动遮蔽疑似密钥。
- 同一套守卫覆盖 Claude Code、Codex、Gemini CLI、Copilot CLI、Cursor、opencode 等十余种代理,提供 AGENT 列区分来源。
- 守卫内部任何错误都放行(exit 0),单个守卫可用 BULKHEAD_DISABLE 或配置单独关闭,不会把工作卡死。
- 提供 doctor 的 Enforcement 段真实跑一次 canary 命令,验证 hook 确实以退出码 2 拦截,而不是只看配置。
- 只分析命令文本,对包裹在脚本文件、shell 函数或别名里的 kill、sleep 不可见,属于尽力而为而非强制隔离。
- memory-guard 与 bulkhead-slot 只看内存,不限制 CPU、磁盘或 GPU;且除非显式调用或开启 autoQueue,没有机制强制所有会话排队。
- 需要额外安装 Node 18+(Claude Code 原生安装器不提供),终端命令与状态行还需全局 npm 安装,属两层安装。
- 每个工具调用增加约 76 ms 开销(冷启动 32 ms 为 Node 启动),10 个会话同时调用时各自等待约 89 ms。
- macOS 上 orphan-reaper 的覆盖依赖 ps 输出 fixture 与真实机测试,Linux 需要能设置 CLAUDE_PID 的 Claude Code 版本,跨平台一致性存在差异。
- 项目配置只能加严不能放宽,误拦需用户手工执行 bulkhead allow 或改全局配置,且已知误报需要通过 issue 反馈修正。
这个 Agent 与同类方案有什么区别?
README 明确对比了通用安全 hook 包:claude-forge(过滤输出中的泄露密钥、拦截管道远程脚本、阻止破坏性 SQL)、dcg(destructive_command_guard)和 cc-safety-net(claude-code-safety-net)覆盖大范围破坏性 shell 与 git 命令。bulkhead 的定位不同:处理同机多会话在进程所有权、端口、共享内存与共享 git 树上的相互干扰,只有 basics 规则与这些包重叠,可用 BULKHEAD_DISABLE=basics 关闭后与它们并行使用。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| claude-bulkhead 当前 | 78 · 表现良好 | — | ★ 35 | 今天 | JavaScript | Codex · Claude Code |
| Kander | 60 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 331 | 1 天前 | Go | Codex · Claude Code |
| Agetor | 76 · 表现良好 | — | ★ 137 | 今天 | TypeScript | Codex · Claude Code |
| Mux 编码代理多路复用器 | 63 · 存在缺口 | 桌面应用免费 + 模型费 | ★ 2.1k | 今天 | TypeScript | — |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
SECURITY.md 与 FAQ 明确说明无遥测、无网络请求,仅本地回环探测端口,数据流透明度高(3)。依赖为零运行时依赖,devDependencies 精确锁定版本,publish 工作流用 OIDC 可信发布且 action 按 SHA 固定,依赖安全良好(3)。但 orphan-reaper 会按 PID 停止进程、bulkhead remote 会经 SSH 把代码与未提交改动发到远端、worktree 会复制 .env,这些外部副作用虽有 dry-run 与用户确认提示,仍属实质写/停操作,故 least_privilege 与 external_effects 仅给 2。敏感数据处理方面,SECURITY.md 承认被拦截命令(可能含 token)会写入 events.jsonl/guards.log,仅提供 BULKHEAD_NO_LOG 关闭,secrets-guard 默认关闭,故扣至 2。回滚有 uninstall 步骤与备份机制,但状态目录与配置改动无自动回滚,给 2。来源归属有作者与仓库链接,但发布者未经 FollowAgents 验证,仅给 1。
AGENTS.md 与 README 一致声明 fail-open(任何错误 exit 0)、纯函数决策、注入时钟与进程快照,自洽性尚可(2),但部分行为(如 76ms 延迟、3700+ 测试徽章)为断言,未在包内验证。依赖可用性优秀:Node 18+ 标准库、零运行时依赖、CI 覆盖三平台与多 Node 版本(3)。失败消息方面有 blocked() 规则名与替代命令提示,但样本中未见完整错误分类与恢复指引,给 2。
受众与场景覆盖多会话、子代理、多 agent(Codex/Gemini/Copilot/Cursor 等),场景描述具体(3)。能力边界在 SECURITY.md 与 FAQ 中明确承认正则匹配可被脚本/别名/编码绕过,非沙箱(3)。触发精度依赖正则文本匹配,FAQ 自承可绕过且可能误报,给 2。环境适配覆盖 Windows/macOS/Linux 与多 Node 版本,CI 矩阵佐证(3)。
信息架构清晰:README、docs/guards、docs/commands、docs/configuration、FAQ 分层(3)。安装说明详尽,含插件、npm、多 agent 安装(3)。命名稳定性方面版本号在 plugin.json/package.json/gemini-extension.json 一致为 0.3.7,但样本未见 CHANGELOG 内容,给 2。示例与 FAQ 丰富(3)。已知局限在 SECURITY.md 与 FAQ 明确列出(3)。LICENSE 为 MIT 且元数据一致(3)。版本化有版本号与 publish 工作流,但 CHANGELOG 未在样本中展示,给 2。维护责任仅有作者名与 issues 链接,发布者未验证,给 1。
输出可用性高:block 消息给出替代命令,status/top/log/doctor 等 CLI 输出结构化(3)。边际价值真实但依赖多会话场景,单会话仅部分 guard 生效,FAQ 自承可能不需要,给 2。成本收益方面每工具调用约 76ms 开销、需 Node 18+,对单会话用户收益有限,给 2。
claim_traceability:README 引用具体 GitHub issue 编号与 docs 链接,可追溯(2),但性能与测试数量为断言。cross_source_corroboration:README、SECURITY.md、FAQ、AGENTS.md 相互印证 fail-open 与无网络(2),但测试通过率与 3700+ 测试未在包内可验证。fact_inference_separation:文档区分了已实现行为与局限,但部分性能数字与徽章属推断性声明,给 2。
- 被拦截命令(可能含 token 等敏感信息)会写入 events.jsonl 与 guards.log,需设置 BULKHEAD_NO_LOG=1 才能关闭。
- orphan-reaper 会按 PID 停止进程,bulkhead remote 会经 SSH 把代码与未提交改动发送到远端,使用前应确认目标与范围。
- secrets-guard 默认关闭,敏感文件保护需手动启用。
- 正则匹配可被脚本、别名或编码命令绕过,不能作为对抗恶意或提示注入代理的沙箱。
- 发布者未经 FollowAgents 验证,身份未知;性能与测试数量声明未在包内独立验证。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
发布说明摘录
bulkhead scan asks once for a GitHub star, after the first report that found commands bulkhead would have stopped. It prints the repository link and a gh command, writes star-asked to the state folder before printing, and never asks again. --json, --share and --explain never ask.在 GitHub 查看 ↗ -
发布说明摘录
Fixed - basics rm-root blocks cmd /c "rmdir /s /q \"D:\path\"" run from PowerShell or cmd. Neither cmd.exe nor PowerShell treats \" as an escaped quote, so rd gets a path that starts at \, the root of the current drive; the same line from Antigravity wiped drive D (a r/google_antigravity report). rd /s and del /s targets that start with \" (or with \D: once PowerShell has ended its string at \") are blocked, and so is del /s of \. The message suggests Remove-Item -LiteralPath '<path>' -Recurse or cmd /c rmdir /s /q "<path>" without backslash-escaped quotes. From …在 GitHub 查看 ↗ -
v0.5.0 0.5.0: xargs-split and link-following deletes, home app data, PowerShell $home, Pi and four more agents
发布说明摘录
0.5.0 adds guards for four more ways agents deleted real data this autumn, closes the holes a reviewer found in 0.4.0's root check, and adds Pi, Qwen Code, Kimi Code, Grok Build and Antigravity. New blocks - rm-xargs-split: xargs without -0/-d running rm -r, or xargs dirname/basename feeding an rm -r later in the pipeline. From a r/ClaudeCode report where xargs -n1 dirname split Application Support at the space, returned ~/Library, and rm -rf deleted it. Use find ... -print0 | xargs -0 rm -rf -- or find ... -delete. …在 GitHub 查看 ↗
常见问题
它会不会明显拖慢 Claude Code?
拦截错了怎么办?
会不会把数据发到外部?
只开一个会话还有用吗?
支持哪些系统和代理?
claude-bulkhead 开源吗?
claude-bulkhead 安全吗?
claude-bulkhead 还在维护吗?
claude-bulkhead 是谁开发的?
谢谢反馈,我们会据此改进页面。