claude-bulkhead

Hooks that keep parallel coding-agent sessions from killing each other's servers, stealing ports, or sweeping your edits into a commit.

Stars
★ 35
Last updated
today
License
MIT
Primary language
JavaScript

At a glance

Works with
Portable with changesCodex · Claude Code
You'll need
Node.js 18+gitShell / CLILocal filesystem
Typical use
Developers running several Claude Code sessions on one repository, each in its own git worktree, who fear one session running pkill node and taking down the others' dev servers.
Main limitation
It inspects command text only; kills or sleeps hidden inside script files, shell functions or aliases are invisible, so it is best-effort rather than a hard sandbox.
Maintenance
Commits in the last 30 dayslast commit 2026-11-20latest release v0.5.2 (2026-11-20)
Source review
78/100 · Good

What does this agent do, and when should you use it?

claude-bulkhead is a set of dependency-free Node hook scripts for Claude Code that run before every Bash, PowerShell, Read and Edit call. Each guard reads the command text and only when it matches does it consult the process table, listening sockets, ~/.claude/sessions records, free RAM or git state to decide whether the action would hurt another live session or subagent. A block is exit code 2 plus a message naming the safer command to run instead; any internal error lets the call through. The same guards load into Codex, Gemini CLI, Copilot CLI, Cursor, opencode and several other agents, and the project ships a CLI with status, top, log, doctor, scan, worktree and remote subcommands. It runs on Windows, Linux and macOS with no daemon, no telemetry and no network calls apart from an optional user-configured SSH remote runner.

Once installed it registers guards that each exist as a separate Node script and can be switched off individually via BULKHEAD_DISABLE or config. kill-guard blocks kills by program name (pkill, killall, taskkill /IM, Stop-Process -Name) and mass kills while another session is alive; port-guard blocks starting a dev server on a port another session already serves, or killing that server by port; memory-guard refuses heavy builds and test runs below a free-RAM floor and works with bulkhead-slot to queue jobs against one shared budget; checkout-guard blocks branch switches, stash, reset --hard, git add -A and deleting a folder another live session is working in; disk-guard blocks whole-disk du/find and parallel scans; wait-guard blocks foreground sleep loops longer than the limit; orphan-reaper stops dev servers, test workers, watchers and headless browsers left behind when a session exits. The CLI adds bulkhead status/top/log/doctor/scan/worktree/remote/allow/explain, an events.jsonl block log, a status line helper and a transcript replay that estimates what would have been blocked.

  1. Developers running several Claude Code sessions on one repository, each in its own git worktree, who fear one session running pkill node and taking down the others' dev servers.
  2. Teams sharing a single checkout where git add -A from one session could sweep another session's half-finished edits into a commit.
  3. People running Claude Code alongside Codex, Gemini CLI, Cursor, Copilot CLI or opencode on the same machine and wanting one guard layer across all of them.
  4. Engineers whose subagents launch Playwright, next build and test suites simultaneously, who want heavy jobs queued against one RAM budget instead of freezing the machine.
  5. Anyone deciding whether to adopt it: /bulkhead:scan 30d replays a month of transcripts and counts how many commands the guards would have stopped.
  6. Users tired of dev servers and test workers outliving the sessions that started them and holding ports and RAM indefinitely.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • npm install -g claude-bulkhead
  • npx claude-bulkhead top
Config files
~/.cursor/plugins/local/bulkhead ~/.claude/bulkhead/config.json .claude/bulkhead.json .env
Runtime
Node.js 18
Install notes cover
Windows

How do you install or deploy this agent?

Node 18 or later must be on PATH (check with node --version). Inside Claude Code, add the marketplace and install the plugin:

/plugin marketplace add dooly6276/claude-bulkhead
/plugin install bulkhead@bulkhead

Optional global npm install for terminal commands, the status line, bulkhead-slot and setup for other agents:

npm install -g claude-bulkhead

Other agents load the same guards, for example:

copilot plugin marketplace add dooly6276/claude-bulkhead
git clone https://github.com/dooly6276/claude-bulkhead ~/.cursor/plugins/local/bulkhead
gemini extensions install https://github.com/dooly6276/claude-bulkhead
codex plugin marketplace add dooly6276/claude-bulkhead
codex plugin add bulkhead@bulkhead

How do you use this agent?

After install the guards run automatically on every Bash, PowerShell, Read and Edit call. First, replay your history to see what would have been blocked (read-only, nothing leaves the machine):

/bulkhead:scan 30d

Verify the hooks actually enforce:

/bulkhead:doctor

Watch sessions, RAM, ports and queued jobs live from another terminal:

npx claude-bulkhead top

Review blocks and release a false positive (allow can only be run by you, not by the agent):

bulkhead log --summary --since 7d
bulkhead allow 7F3K

Tune thresholds in the global config ~/.claude/bulkhead/config.json; a project .claude/bulkhead.json can only make guards stricter:

{
  "killGuard": { "allowNames": ["ffmpeg"] },
  "waitGuard": { "limitSeconds": 300 },
  "portGuard": { "ignorePorts": [9229] }
}

Create a ready-to-use worktree with .env files copied and a stable port:

bulkhead worktree add fix-login

What are this agent's strengths and limitations?

Pros
  • Decides on session ownership rather than a flat blacklist: it blocks only when a concrete other live session is affected, and the block message carries the safer command to run.
  • Zero dependencies, no background daemon, no telemetry and no network calls other than the opt-in SSH remote; logs stay in the local state directory.
  • bulkhead scan replays past transcripts so you can quantify the value before adopting, and it masks anything resembling a secret before printing.
  • One guard layer covers Claude Code plus Codex, Gemini CLI, Copilot CLI, Cursor, opencode and several more, with an AGENT column distinguishing sessions.
  • Any error inside a guard exits 0, and each guard or rule can be disabled individually, so a broken guard cannot stop your work.
  • bulkhead doctor proves enforcement by running an installed hook against a canary and checking exit code, message and latency, not just config presence.
Limitations
  • It inspects command text only; kills or sleeps hidden inside script files, shell functions or aliases are invisible, so it is best-effort rather than a hard sandbox.
  • memory-guard and bulkhead-slot only consider RAM, not CPU, disk or GPU, and nothing forces every session to queue unless autoQueue is enabled or the slot is called explicitly.
  • Requires Node 18+ installed separately (the native Claude Code installer does not provide it), and terminal commands plus the status line need a second global npm install.
  • Adds roughly 76 ms per tool call on a MacBook Pro with Node 24, of which 32 ms is Node startup; ten simultaneous callers each wait about 89 ms.
  • Platform parity varies: macOS orphan-reaper was tested with ps fixtures and a real Mac, while Linux needs a Claude Code version that sets CLAUDE_PID for tool shells.
  • Project config can only tighten guards, so misfires require you to run bulkhead allow or edit the global file, and known false positives go through an issue template.

How does this agent compare with similar options?

The README explicitly contrasts bulkhead with general safety hook packs: claude-forge (filters leaked secrets from output, blocks piped remote scripts, stops destructive SQL), dcg (destructive_command_guard) and cc-safety-net (claude-code-safety-net), which cover destructive shell and git commands broadly. bulkhead targets a different problem — sessions on one machine colliding over process ownership, ports, shared RAM and a shared git tree — and only its basics rules overlap, so BULKHEAD_DISABLE=basics lets it run alongside those packs.

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
claude-bulkhead This agent 78 · Good — ★ 35 today JavaScript Codex · Claude Code
Kander 60 · Some gaps CLIFree + model costs ★ 331 1d ago Go Codex · Claude Code
Agetor 76 · Good — ★ 137 today TypeScript Codex · Claude Code
Mux - Coding Agent Multiplexer 63 · Some gaps Desktop appFree + model costs ★ 2.1k today TypeScript —

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Good
78/ 100 5-point scale 3.9 / 5
This review covers the source as of Nov 12, 2026. The project has shipped 4 stable release(s) since, which have not been re-reviewed. The score and verdict describe the reviewed version only. Recent releases ↓
Trust 21/29
Reliability 11/14
Adaptability 16/18
Convention 15/18
Effectiveness 10/13
Verifiability 5/8
Why each dimension lost points
Trust21 / 29 · 3.6/5

SECURITY.md and FAQ state no telemetry and no network calls, only localhost port probes, giving strong data-flow transparency (3). Zero runtime dependencies, exact-pinned devDependencies, OIDC trusted publishing and SHA-pinned actions give good dependency security (3). However orphan-reaper stops processes by PID, bulkhead remote ships code and uncommitted changes over SSH, and worktree copies .env; these are real external effects with dry-run and confirmation prompts, so least_privilege and external_effects are capped at 2. Sensitive data: SECURITY.md admits blocked commands (possibly containing tokens) are written to events.jsonl/guards.log with only BULKHEAD_NO_LOG to disable, and secrets-guard is off by default, so 2. Rollback has uninstall steps and backups but no automatic rollback of state/config, so 2. Source attribution names the author and repo but the publisher is unverified, so 1.

Reliability11 / 14 · 3.9/5

AGENTS.md and README consistently state fail-open (any error exits 0), pure decision functions, injected clocks and process snapshots, so self-consistency is adequate (2), though some behaviors (76ms latency, 3700+ test badge) are asserted, not verified in-packet. Dependency availability is strong: Node 18+ stdlib, zero runtime deps, CI across three platforms and multiple Node versions (3). Failure messages include blocked() rule names and safer-command hints, but the sample lacks full error taxonomy and recovery guidance, so 2.

Adaptability16 / 18 · 4.4/5

Audience and scenarios cover multi-session, subagents and many agents (Codex/Gemini/Copilot/Cursor etc.) with concrete scenarios (3). Capability boundaries are explicitly acknowledged in SECURITY.md and FAQ: regex matching can be bypassed by scripts/aliases/encoding, not a sandbox (3). Trigger precision relies on regex text matching, self-admitted bypassable and prone to false positives, so 2. Environment fit covers Windows/macOS/Linux and multiple Node versions, corroborated by CI matrix (3).

Convention15 / 18 · 4.2/5

Information architecture is clear: README, docs/guards, docs/commands, docs/configuration, FAQ layered (3). Install notes are thorough across plugin, npm and multiple agents (3). Naming stability: version 0.3.7 consistent across plugin.json/package.json/gemini-extension.json, but no CHANGELOG content in the sample, so 2. Examples and FAQ are rich (3). Known limitations are explicitly listed in SECURITY.md and FAQ (3). LICENSE is MIT and metadata consistent (3). Versioning has version numbers and a publish workflow, but CHANGELOG is not shown, so 2. Maintenance responsibility is only an author name and issues link with an unverified publisher, so 1.

Effectiveness10 / 13 · 3.8/5

Output usability is high: block messages give safer commands, and status/top/log/doctor produce structured output (3). Marginal value is real but depends on multi-session use; single-session only some guards apply and the FAQ admits it may not be needed, so 2. Cost-benefit: ~76ms per tool call overhead and Node 18+ requirement limit value for single-session users, so 2.

Verifiability5 / 8 · 3.1/5

claim_traceability: README cites specific GitHub issue numbers and docs links, traceable (2), but performance and test counts are assertions. cross_source_corroboration: README, SECURITY.md, FAQ and AGENTS.md mutually corroborate fail-open and no-network claims (2), but test pass rates and 3700+ tests are not verifiable in-packet. fact_inference_separation: docs distinguish implemented behavior from limitations, but some performance numbers and badges are inferential claims, so 2.

Risks and how to mitigate them
  • Blocked commands (possibly containing tokens) are written to events.jsonl and guards.log; set BULKHEAD_NO_LOG=1 to disable.
  • orphan-reaper stops processes by PID and bulkhead remote ships code and uncommitted changes over SSH; confirm targets and scope before use.
  • secrets-guard is off by default; sensitive-file protection must be enabled manually.
  • Regex matching can be bypassed by scripts, aliases or encoded commands; it is not a sandbox against hostile or prompt-injected agents.
  • Publisher is unverified by FollowAgents and identity is unknown; performance and test-count claims are not independently verified in-packet.
Evidence confidence: Low Reviewed Nov 12, 2026 Reviewed revision d465a51a3cb0 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/claude-bulkhead.svg)](https://followagents.com/en/agents/claude-bulkhead)
<a href="https://followagents.com/en/agents/claude-bulkhead"><img src="https://followagents.com/badge/claude-bulkhead.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.5.2
    Release notes excerpt
    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.
    View on GitHub ↗
  2. v0.5.1
    Release notes excerpt
    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 …
    View on GitHub ↗
  3. v0.5.0 0.5.0: xargs-split and link-following deletes, home app data, PowerShell $home, Pi and four more agents
    Release notes excerpt
    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. …
    View on GitHub ↗

FAQ

How much latency does it add to Claude Code?
About 76 ms per tool call on a MacBook Pro with Node 24, of which 32 ms is starting Node; ten sessions calling at once each wait about 89 ms. Slow lookups such as the process list only happen when a command matches, and the status line is cached for 5 seconds.
What if it blocks something I meant to run?
Run bulkhead log to see the exact command and rule, then run bulkhead allow <code> from the block message to let that identical command through once within 10 minutes. For a permanent change, edit the global ~/.claude/bulkhead/config.json; the agent cannot approve its own blocks.
Does it send data anywhere?
No telemetry and no network calls; the only socket is port-guard's localhost probe to see whether a port answers. Logs rotate at 1 MB in the state directory. The single exception is bulkhead remote, which connects over SSH to a host you configured and only when you run it.
Is it worth using with just one session?
Yes. kill-guard, wait-guard, memory-guard and basics apply to a single session and its subagents; port-guard and checkout-guard only act when another session is alive, and orphan-reaper cleans up after exited sessions.
Which operating systems and agents are supported?
Windows, Linux and macOS with Node 18 or later. Beyond Claude Code it supports Codex, Gemini CLI, Copilot CLI, Cursor, Windsurf, Droid, Devin, Cline, opencode and Amp via bulkhead setup <agent> or plugin marketplaces.
Is claude-bulkhead open source?
Yes. The source code is on GitHub (dooly6276/claude-bulkhead) under the MIT licence.
Is claude-bulkhead safe to use?
FollowAgents' FARS review (Nov 12, 2026) scored claude-bulkhead 21/29 on trust and safety. None of the eight safety controls the review checks for was missing outright. The repository has changed since that review.
Is claude-bulkhead still maintained?
Yes. The latest commit on GitHub is from 2026-11-20, within the last 30 days. The latest release is v0.5.2 (2026-11-20).
Who makes claude-bulkhead?
claude-bulkhead is published on GitHub by the account dooly6276. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts