claude-bulkhead
Hooks that keep parallel coding-agent sessions from killing each other's servers, stealing ports, or sweeping your edits into a commit.
- Source repo
- dooly6276/claude-bulkhead
- Stars
- ★ 35
- Last updated
- today
- License
- MIT
- Primary language
- JavaScript
- FA score
- 78/100 · Good
At a glance
- Works with
- Portable with changesCodex · Claude Code
- You'll need
- 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.
- 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.
- Teams sharing a single checkout where git add -A from one session could sweep another session's half-finished edits into a commit.
- 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.
- 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.
- Anyone deciding whether to adopt it: /bulkhead:scan 30d replays a month of transcripts and counts how many commands the guards would have stopped.
- 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-bulkheadnpx 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@bulkheadOptional global npm install for terminal commands, the status line, bulkhead-slot and setup for other agents:
npm install -g claude-bulkheadOther agents load the same guards, for example:
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@bulkheadHow 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 30dVerify the hooks actually enforce:
/bulkhead:doctorWatch sessions, RAM, ports and queued jobs live from another terminal:
npx claude-bulkhead topReview blocks and release a false positive (allow can only be run by you, not by the agent):
bulkhead log --summary --since 7d
bulkhead allow 7F3KTune 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-loginWhat are this agent's strengths and limitations?
- 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.
- 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?
Why each dimension lost points
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.
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.
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).
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.
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.
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.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
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 ↗ -
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 ↗ -
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?
What if it blocks something I meant to run?
Does it send data anywhere?
Is it worth using with just one session?
Which operating systems and agents are supported?
Is claude-bulkhead open source?
Is claude-bulkhead safe to use?
Is claude-bulkhead still maintained?
Who makes claude-bulkhead?
Thanks — we use this to improve the page.