dooly6276/bulkhead
Guards for a machine where many coding agent sessions run at once: blocks name-based kills of another session's processes, port collisions, git commands that would move or delete another session's tree, whole-disk scans and long foreground sleeps, and holds heavy commands back when RAM runs low.
Changelog
0.5.1 - 2026-11-14
Fixed
- basics
rm-rootblockscmd /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 /sanddel /stargets that start with\"(or with\D:once PowerShell has ended its string at\") are blocked, and so isdel /sof\. The message suggestsRemove-Item -LiteralPath '<path>' -Recurseorcmd /c rmdir /s /q "<path>"without backslash-escaped quotes. From bash (Git Bash) the escapes are removed before cmd reads the line, socmd //c "rmdir /s /q \"D:\work\out\""gets the whole path and passes; a single quotedcmd /cargument from bash or PowerShell is now read as that shell's value, so such a path is checked like any otherrd /starget.
0.5.0 - 2026-11-14
Added
- Pi coding agent: the npm package is now a Pi package.
pi install npm:claude-bulkheadloads an extension that runs the guards on Pi'stool_callfor thebashandpowershelltools and blocks with bulkhead's message;bulkhead setup piwrites the same extension to~/.pi/agent/extensions/bulkhead.js. Pi sessions show inbulkhead status, andpkill piis blocked like other agents. bulkhead setup qwen|kimi|grok|antigravityandbulkhead hook --agent qwen|kimi|grok|antigravity: Qwen Code (PreToolUsein~/.qwen/settings.json, Qwen Code sessions are recognized), Kimi Code (a[[hooks]]table appended to~/.kimi-code/config.toml), Grok Build (~/.grok/hooks/bulkhead.json) and Antigravity (abulkheadhook group in~/.gemini/config/hooks.json, always answeringallowordenysince Antigravity requires a decision).- basics
rm-xargs-split: a pipeline wherexargswithout-0/--nullor-d/--delimiterrunsrm -r, or runsdirnameorbasenamewhose output anrm -rlater in the pipeline deletes, is blocked. Without them xargs splits paths at spaces and reads quotes and backslashes, so rm gets shorter paths, and dirname turns a piece such as~/Library/Applicationinto~/Library:find ~/Library/Application\ Support/... | xargs -n1 dirname | xargs rm -rfwiped~/Library(from a r/ClaudeCode report).xargs -I {}without-0is blocked too, since it still splits at newlines and reads quotes and backslashes.find ... -print0 | xargs -0 rm -rf,git ls-files -z | xargs -0 rm -rf,xargs rm -f < listandecho a b | xargs rm -rfpass. Turn it off withbasics.rmXargsSplit. - basics
rm-through-link:git worktree remove --forceon a folder that holds a junction or symbolic link to an existing folder outside it is blocked on every platform, and so is a PowerShellRemove-Item -Recurse(or an alias of it) of such a folder on Windows, where Windows PowerShell 5.1 follows junctions. Git Bash'srm -rfand cmd'srd /sdo not follow junctions and pass, sorm -rf node_modulesin a Windows workspace is not stopped. Two old worktrees with junctions toD:\...\modelsand a.venvtook about 230 GB of real data with them (from a r/ClaudeAI report).rm -rf link/,link/*andlink/.with a symbolic link to a folder are blocked on every platform: the slash makes rm delete the target (on macOS the target folder itself). The walk stops at 2000 entries or 6 levels and lets the command through past that; on a 2000-entry folder it adds about 2 to 5 ms. The message names the link and says to remove it first (cmd /c rmdir <link>,unlink <link>). Turn it off withbasics.rmThroughLink.
Changed
- basics
rm-rootalso blocks a whole folder in home that holds app data, documents or keys one level deeper (~/Library/Application Support,~/Library/Containers,~/AppData/Roaming,~/AppData/Local,~/.local/shareand similar), another user's home (/Users/<name>,/home/<name>,C:\Users\<name>,/mnt/c/Users/<name>) and those folders in it, andC:\UsersandC:\Users\<name>written out on macOS and Linux. Folders deeper inside, such as~/Library/Caches/xor~/.config/<app>, still pass. - basics
rm-root,rm-empty-varandrm-git-dirread PowerShell deletes with-Recursealone, without-Force, in any spelling PowerShell accepts (-r,-rec,-Recurse:$true), throughRemove-Item,ri,rm,del,rdandrmdir. A target in parentheses is read too:Remove-Item -Recurse -Force (Split-Path $home) -ErrorAction SilentlyContinuedeleted underC:\Users, because$homeis PowerShell's read-only automatic variable for the user profile (from anomalyco/opencode#62825). It is blocked with a note on what$homeis, as are(Split-Path $env:USERPROFILE),(Split-Path -Qualifier $home),$env:HOMEPATHand$env:SystemDrive\, also insidepowershell -Commandandpwsh -c.
Fixed
- basics
rm-rootfills in a variable the same line sets before judging the path, soD=/; rm -rf "$D/",D=/; rm -rf $D/,D=~; rm -rf "${D:?}"/*,D=$HOME; rm -rf "$D"andD='C:\'; rm -rf "${D:?}/"are blocked likerm -rf /. A variable set to a path command applied to a drive root,/or home, such asD="$(cygpath -u 'C:\')",D=$(wslpath 'C:\'),D=$(realpath /)orD=$(readlink -f ~), counts as that root when the delete names the variable alone or followed only by/or/*:"${D:?}/"proves the value is not empty, not that it is not the root.rm -rf "${D:?}/sub"still passes.C:\,/mnt/cand/cygdrive/ccount as drive roots on every platform, and/mnt/c/<folder>as a top-level folder of the drive. Reported by foma-agent in anthropics/claude-code#95426. - basics
rm-empty-varsuggestedrm -rf "${BUILD_DIR:?}/*"forrm -rf "$BUILD_DIR"/*, with the glob inside the quotes, where it never expands. The hint now keeps a trailing*or.*outside:rm -rf "${BUILD_DIR:?}"/*. For a path command that prints a root it suggests naming a folder under it, and for$env:Xand%X%it shows the PowerShell and cmd checks instead of a bash form.
0.4.0 - 2026-11-14
Added
- Bulkhead recognizes Aider CLI sessions in status and session ownership checks.
- basics
rm-empty-var:rm -rf $D/,rm -rf "$D"/*,rm -rf $(cygpath -u "$X")/andrsync --delete src/ $D/are blocked when the variable is not set to something non-empty earlier in the same shell, because an empty or unset variable (or a command that prints nothing) turns the path into/(anthropics/claude-code#109735). Deleting the whole output of a path command, such asrm -rf "$(cygpath -u 'C:\')", which prints/c/, is blocked too (anthropics/claude-code#95426 lost 600 GB)."${D:?}/","$TMPDIR/foo"andD=$(mktemp -d) && rm -rf "$D"/pass. AlsoRemove-Item -Recurse -Force $env:X\,rd /s /q %X%\, and the same commands insidebash -candwsl -- bash -lc. Withwsl -- bash -lc '...'an assignment inside the string does not count, because wsl hands the line to a Linux shell that expands the variable first. Applies with a single session. Turn it off withbasics.rmEmptyVar. - basics
rm-unquoted-var:rm -rf $DwithDunquoted is blocked when the value, set earlier on the line or in the environment, has a space or a wildcard, since bash splits it into several paths and deletes each (anthropics/claude-code#107271). Turn it off withbasics.rmUnquotedVar. - basics
rm-git-dir:rm -rf .git,rm -rf path/.gitandfind . -name .git -exec rm -rf {} +are blocked when that.gitis an existing folder, since the repository's history goes with it (anthropics/claude-code#107274). A.gitthe same line creates, such as aftergit clone, passes. Turn it off withbasics.rmGitDir. - kill-guard
bsd-pkill: on macOS and the BSDs,pkillwith a long option (--signal,--full) or with more than one pattern is blocked, also with a single session. BSDpkillhas no long options and reads everything after the first pattern as another pattern, sopkill -f "gcloud.py compute" -u me --signal 0, meant as an existence check, also matched0and sent SIGTERM to about 66 processes, every other Claude Code session among them (anthropics/claude-code#109627). The message suggestspgrep -f '<pattern>'for an existence check. Turn it off withkillGuard.bsdPkill.
Changed
bulkhead scan --sharelists what people fear first, in plain words: kills by name that would have hit other sessions' processes, recursive deletes,git add -Aof another session's edits, branch switches in a shared tree, port clashes. The rest folds into one line and the foreground waits come last. No rule names appear in the share text any more (before, a rule without a description showed asbasics self-allow).
Fixed
- kill-guard reads
pkillarguments the way the platform'spkilldoes. On Linux, options written after the pattern (pkill -f x --signal 0,pkill -f x -P $$) are options, as procps reads them, so a signal-0 check or a-Pscope there passes. On macOS, every extra operand is a pattern, and each gets the same checks as the first.
0.3.7 - 2026-11-12
Changed
- The bulkhead skill now fits every agent that loads it, not only Claude Code. It says that orphan-reaper's cleanup at session end is Claude Code only and that in Copilot CLI and the other agents you stop your own servers before you finish, and it explains how to run
bulkheadandbulkhead-slotwithnodefrom the plugin folder when a plugin-only install (Copilot CLI) does not put them onPATH.
Fixed
- Codex and Copilot CLI sessions are found when
CODEX_HOMEorCOPILOT_HOMEmoves their config folder. Before, a machine with only a moved folder skipped the process scan for that agent, so its servers and folders were not protected from other sessions.
0.3.6 - 2026-11-12
Changed
- Releases are published to npm by GitHub Actions with npm trusted publishing (
.github/workflows/publish.yml), so each version on npm carries a provenance statement linking it to this repository and the commit it was built from. The same workflow attaches the Gemini CLI extension archive to the release. The guards are unchanged from 0.3.5.
0.3.5 - 2026-11-12
Added
- kill-guard
broad-pattern:pkill -f <pattern>is blocked when the pattern matches a desktop app (a process inside an.appbundle) or 8 or more processes outside the session's own tree, also when only one session runs.pkill -f cat, meant for one stuckcat, matches every app under/Applications; on macOS, BSDpkillreads-n,-uand-Pwritten after the pattern as more patterns, so they narrow nothing (anthropics/claude-code#100684, #107867). Processes the session started do not count. Turn it off withkillGuard.broadPattern.
0.3.4 - 2026-11-12
Added
- Gemini CLI extension:
gemini extensions install https://github.com/dooly6276/claude-bulkheadinstalls the guards as an extension (gemini-extension.json, aBeforeToolhook onrun_shell_command). The extension is the release assetbulkhead-gemini-extension.tar.gz, built byscripts/build-gemini-extension.js. - Codex plugin:
codex plugin marketplace add dooly6276/claude-bulkhead, thencodex plugin add bulkhead@bulkheadinstalls the guards as a Codex plugin (.codex-plugin/plugin.json, aPreToolUsehook onBash). The marketplace entry installs the npm package, which now ships.codex-plugin/andcodex/.
Fixed
- Windows:
bulkhead worktree pruneandlistnow match a session or the current folder to its worktree when one of the two paths uses an 8.3 short name (C:\Users\RUNNER~1\...) and git prints the long one. Before, prune could remove a worktree a live session was working in, or the one it was run from. The Windows CI jobs pass again: the other failures were tests that assumed/bin/sh, paths without a drive letter, or the Linux time limit for the 1 MB fuzz case.
0.3.3 - 2026-11-12
Changed
- A guard that throws is still skipped so the other guards run, but the error is now written to the event log with rule
guard-errorand toguards.log, sobulkhead logandbulkhead topshow it instead of it looking like a clean pass.
Fixed
- port-guard reads a very long pipeline (hundreds of thousands of segments) in a fraction of the time: dev-server detection looks a program up by name instead of testing every known tool against every segment. This also keeps the 1 MB fuzz case inside its time limit on slower CI runners.
0.3.2 - 2026-11-12
New
- Plugin bundles for Copilot CLI, Cursor and opencode. The repository is now also an Agent Plugins 1.0.0 plugin (
plugin.jsonat the root, hooks incom.github.copilot/hooks/hooks.json) that Copilot CLI installs withcopilot plugin marketplace add dooly6276/claude-bulkheadandcopilot plugin install bulkhead@bulkhead; a Cursor plugin (.cursor-plugin/plugin.jsonwith its own.cursor-plugin/hooks.json); and an opencode plugin from npm ("plugin": ["claude-bulkhead"], entryopencode/plugin.mjs). Each callsbulkhead hook --agent <name>from the plugin's own copy, so the guards are the same as withbulkhead setup <agent>and nothing is written to the agent's config. The Claude Code plugin andhooks/hooks.jsonare unchanged.
0.3.1 - 2026-11-12
Changed
- A project file can only make bulkhead stricter. A repository's
.claude/bulkhead.jsoncomes with whatever you clone, so it can no longer take names off kill-guard's list, ignore ports, lengthen the wait limit, lower the RAM floor, turn a guard or rule off, turn on auto-queue or add programs for orphan-reaper to stop. Those settings are read from the global file only; in a project file they are ignored with a warning inbulkhead config,bulkhead doctorand the startup notice. A project can still add shared names, protected branches and secret patterns (added to the global lists, no longer replacing them), tighten limits and turn guards on. A project preset applies only where it is stricter. Block messages now point to the global file. - The skill no longer runs
bulkhead remote runon its own. It shows the user the remote, the commit and every uncommitted change it would send, any--filesit would add, and the command, and runs it only after the user says yes to that run, as/bulkhead:remotealready did. memory-guard's block message says the same.
Fixed
bulkhead worktree prunecounts a branch as merged when every commit on it was cherry-picked or rebased onto the base, not only when it was merged or squash-merged.
0.3.0 - 2026-11-12
New
- One hook process for every Bash guard.
src/bash-guards.jsruns the guards in a row, text-only checks first and the ones that read git, memory, processes or ports last, and stops at the first block. A Bash call used to start seven Node processes. With 10 sessions making a tool call at the same moment, each now waits about 89 ms instead of 318 ms (611 ms to 109 ms with 20).node scripts/bench-hooks.js 9 --sessions 10measures it on your machine. bulkhead explain -- <command>shows what every guard would say about a command, with the evidence (which session owns the process or port, how much RAM is free) and how to allow it, without running anything.- Allow once. Every block message ends with a code: the user runs
bulkhead allow <code>in their own terminal and the same command passes once within 10 minutes. The new basics ruleself-allowblocks the agent from runningbulkhead allowor writing the allow files itself, in 25 spellings. - Presets.
bulkhead config --preset quiet|normal|strict [--project].quietkeeps only what protects one session from another and the rules that cannot be undone;stricttightens the limits, scaled to the machine's RAM, and turns secrets-guard on. bulkhead worktree add|list|prune.addmakes../<repo>-<name>on a new branch, copies your.envfiles (or what.worktreeincludelists), installs dependencies with the lockfile's package manager and writes a stablePORTto.env.local.listshows branch, age, changes, ahead and behind, live session and port.pruneremoves worktrees that are merged (squash and rebase merges included), clean and idle, never one a live session works in, and is a dry run until--yes.bulkhead port --stablegives a worktree the same port every time, and port-guard suggests it first.- Auto-queue. With
{"memoryGuard":{"autoQueue":true}}, a heavy command is not refused: the hook rewrites it to run throughbulkhead-slotand it starts when there is room. Waiting jobs are served first in, first out, poll once a second, and print their place in line every 30 seconds. - subagent-guard (opt-in,
memoryGuard.subagents) stops new subagents while memory pressure is critical. - edit-guard tells the agent, before it edits a file, that another live session edited the same file in the last 30 minutes, in this tree or another worktree of the repository. Advisory by default;
editGuard.modecan beaskorblock. - secrets-guard (off by default, on in
strict) blocks showing.envfiles, private keys, cloud and registry credentials, and the whole environment to the model, through the Read and Grep tools or a shell command..env.example,ls ~/.ssh,.pubfiles and appending to.envpass. - Codex, Gemini CLI, Copilot CLI, Cursor, Windsurf, Droid, Devin, Cline, opencode and Amp.
bulkhead setup <agent> --writeregisters the same guards in that agent's hook config, with a backup of the original. Their CLI sessions count as sessions for port-guard, checkout-guard andbulkhead status. bulkhead statusandtopshow aSTATEcolumn (working, waiting for you, waiting for a permission) and aBRANCHcolumn, the session and project of each queued job, and duplicate MCP servers that several sessions start. Anotify.commandruns when a session starts waiting for you.bulkhead doctorhas an Enforcement section: it runs a harmless command through each guard and shows the block and how long it took, and finds settings that switch the hooks off, duplicate installs and anodemissing from the hooks'PATH.bulkhead scan --shareprints a short summary with counts only, for a post or a chat.--explain Nshows one hit in full with the part that matched.- orphan-reaper keeps processes started with
BULKHEAD_KEEP=1, SSH tunnels,cloudflaredand databases, and anything matchingorphanReaper.keepPatterns. The next session start tells you what it stopped.
Changed
-
On macOS, free RAM comes from
kern.memorystatus_leveland the memory pressure level instead of avm_statestimate, which counted far too little as free on a Mac with a lot of file cache. memory-guard blocks heavy commands at pressure level 2 or higher. When neither can be read, heavy commands are let through instead of blocked. -
More heavy commands are recognised:
xcodebuild,swift buildandswift test,fastlane,bundle exec,go buildandgo testwith-raceor./..., andnx run|build|test|e2e. -
Block messages name the other session by project and branch, and end with the exact config line that would allow the rule.
-
bulkhead --version,bulkhead help <command>and<command> --help; unknown commands and options that need a number are rejected with a clear message. -
Inside a hook, reading the process table gives up after 4 seconds (8 on Windows) and lets the call through, instead of waiting up to 15 (60).
-
guards.logis rotated at 1 MB likeevents.jsonl, and two hooks rotating at the same moment no longer lose the older log. -
port-guard knows many more servers, each on its default port:
serve,live-server,json-server,puma,gunicorn,hypercorn,fastapi dev, Djangorunserver, Streamlit, Jupyter,trunk, Metro and React Native, VuePress, VitePress, Phoenix, Parcel, Ember, MkDocs, Hugo, Hexo, Zola, mdBook, Netlify and Vercel dev, Rspack, Rsbuild, Spring Boot and more. It reads the port fromphp -S,dotnet run --urls,--server.port,docker run -pand theports:of a compose file, throughpnpm,yarn,npm exec,bunx,uv run, workspaces and wrappers such astimeout,caffeinate,cross-envand(cd web && npm run dev &). The free-port suggestion uses each tool's own flag. -
port-guard catches more ways to kill by port:
lsof ... | awk ... | xargs killwithout-t,PID=$(lsof -ti :3000); kill $PID, loops overlsofoutput,fkill :3000, andnetstat,ssandfuser -n tcp -kpipelines. -
checkout-guard sees more ways to change a shared tree:
git --no-pager add -Aand other global options in front of the subcommand,git ls-files -m | xargs git add,git add $(git ls-files -m),git add "$PWD"and*,checkout -f,stash -a,stash dropandclear,rm -rof a folder,restoreorcheckout --of a folder with uncommitted changes,cherry-pick,revert,am,apply,reset --mergeand--keep, and a mixedresetover staged files.rm -rf ./*,rm -rf .gitandfind . -deletecount as removing a folder another session works in. Eachcdin the command is followed, socd /tmp/x && rm -rf ./*passes. -
New basics rule
protected-deleteblocks deleting a protected branch:git push origin :main,git push --delete origin main,git branch -D main.git branch -dpasses, because git itself refuses to lose unmerged work. -
checkout-guard compares a session file's start time with the process's, so a reused PID no longer counts as a live session.
-
kill-guard sees through more indirection:
echo pkill node | sh,source <(...),bash <(...),eval "$(...)",xargs pkill,busybox, shell functions and variables (cmd=pkill; $cmd node),tmux,screen,script,parallel, shell commands that python, node, perl, ruby or php run from a string, andssh localhost. Dev-server and tool names (next-server,uvicorn,gunicorn,rails,expo,metro,tsc,playwright, Google Chrome and its helpers) are on the shared list, versions included (node22,python3.11), and so are other coding agents (codex,gemini,copilot,cursor-agent). -
While another Claude session is alive, kill-guard also blocks:
kill <pid>,taskkill /PIDandStop-Process -Idof a process in another session's tree;pkill -f <path>that matches another session's command line;pkill -u,kill -1andkill 0;docker ... $(docker ps -q),docker system prune,pm2 killanddocker compose downin another session's project;adb kill-server,adb emu killwithout a serial andsimctl shutdown all; quitting shared apps (Slack, Finder, Dock) and stopping shared services (brew services stop,launchctl bootout,systemctl stop). Each rule has its own switch:killGuard.massKill,dockerMass,deviceKill,appQuit,serviceStopandownerCheck. The process table is read only for these commands. -
kill-guard messages are two lines: who owns what you were about to stop, and the command that stops only yours.
Fixed
- checkout-guard lets these through:
git add -A srcand other stage-all forms with a path,git add -n,git stash push -- <paths>,--helpof any git command, and single-filerestore. In a sample of 20,000 real commands in a shared, dirty tree, it blocked 1,432 instead of 1,962; the 39 newly blocked ones were all tree-changing commands. - basics advice for
git cleanno longer suggestsgit stash push -u, which checkout-guard blocks in a shared tree. - port-guard no longer reads quoted text as a command:
grep -E "next dev|vite"andps | grep -E 'next start|playwright'pass, as dovite --version,vite buildand any tool run with--help. Heredoc bodies fed to python, node or cat are data, not commands. In 160,288 real commands from transcripts, it blocked 12 instead of 28 under the same conditions, and every one of the 12 was a real conflict. - A heredoc is shell code only when a shell reads it (
bash <<EOF,cat <<EOF | sh,ssh localhost bash). Bodies fed towhile read,git,psqlor a script are data; bodies fed to python or node are read in that language. In 161,188 real commands, kill-guard blocked 4 instead of 14 when no other session ran, and wait-guard blocked 1,009 instead of 1,123 at a 10-minute timeout, with no new blocks. - wait-guard reads python
time.sleepand nodesleep/setTimeoutwaits inside heredocs in their own units, ignores them inside strings and comments, and no longer multiplies a script's waits by an earlier shell loop. pkill -f "ssh -N -L 9333"and other specific-fpatterns pass;pkill -f serverandpkill -f "next dev"still block.- Claude Code sessions started by the macOS desktop app were not seen as sessions.
bulkhead doctorreported the plugin as installed when run throughnpxfrom an unrelated copy.
0.2.2 - 2026-11-11
Fixed
bulkhead scanno longer crashes withRangeError: Maximum call stack size exceededon a long history (hundreds of thousands of commands). The span is found with a loop, and a list append in the event log reader no longer spreads a whole file into one call.bulkhead scan 30dnow means--since 30d. It used to ignore the argument and scan everything. Every subcommand now rejects an option or argument it does not know, with its usage text, instead of ignoring it.- The status line counted session files whose pid was alive, so a reused pid counted as a session. It now counts Claude Code processes the way
bulkhead statusdoes, from onepslisting (Windows keeps the pid check). git pullin a tree another session works in gets its own advice (wait for that session to commit or stash, or pull from a clone nobody uses) instead of the worktree advice.
Added
bulkhead scanreads about twice as fast and prints a progress line on stderr when it runs longer than 3 seconds in a terminal.- A block message from kill-guard, wait-guard, disk-guard, checkout-guard and basics ends with one line telling the agent to ask the user when the command was meant, and that the user can allow it in
.claude/bulkhead.json. - checkout-guard
remove-session-dirresolves$PWD,${PWD},$(pwd)and`pwd`to the current folder, sorm -rf "$(pwd)"is caught likerm -rf .. - port-guard checks a
PORT=3000set in the command fornpm start,npm run devand similar scripts, and fornode server.js,tsx,nodemon,bunanddenorunning a file. - kill-guard also blocks killing by name Electron, Simulator, Xcode, postgres, Docker Desktop, Code Helper and Cursor.
- The package can be run without the plugin:
npx claude-bulkhead status,top,scan,doctor. It installs aclaude-bulkheadcommand next tobulkhead. Withnpm install -g claude-bulkhead, the status line command no longer contains the plugin version. - The README opens with a real Claude Code recording of kill-guard blocking
pkill node(docs/demo.gif, re-recorded withdocs/demo.tape), and the install steps come first.
0.2.1 - 2026-11-11
/bulkhead:remotenow shows what a run will upload (the current commit and every uncommitted change, deletions included) and the remote it goes to, and waits for your yes before anything is sent.- The README says that a project's
.claude/bulkhead.jsoncan relax the guards for that repository, so read it in a repository you clone, and thatbulkhead configshows where each setting came from.
0.2.0 - 2026-11-08
New
bulkhead scanreplays the shell commands in your Claude Code transcripts (~/.claude/projects, subagents included) against the guards and prints what they would have stopped: hits per guard and rule, in how many sessions, how many a hook or you already stopped, the newest examples with secrets masked, and the most sessions that ran at once. checkout-guard is rebuilt from which sessions were active in the same git tree at that minute. Read-only, about 200 MB of transcripts a second.--since,--project,--path,-n,--json, and/bulkhead:scan.- disk-guard blocks scans that walk the whole drive or home folder (
du -sh ~,du -sh ~/*,ncdu /,Get-ChildItem C:\ -Recurse,dir /s C:\),find /andfind ~without-maxdepth, and disk scans run in parallel (xargs -P, GNUparallel,&in a loop,ForEach-Object -Parallel). The disk is shared by every session, and these stall all of them for minutes. - checkout-guard
stage-allblocksgit add -A,git add .,git add -uandgit commit -ain a tree with changes when another live session works in it: the other session's half-finished edits would go into your commit. Named files pass. - checkout-guard
remove-session-dirblocksrm -rf,Remove-Item -Recurse -Force,rd /sandgit worktree removeof the folder another live session works in, or a folder above it. - checkout-guard
worktree-force-links(Windows) blocksgit worktree remove --forceon a worktree with junctions or symlinks in its first two levels, which git has followed into the main checkout'snode_modules. - basics
agent-authorblocks commits authored as Claude or Anthropic:--author,git config user.name/user.email,git -c user.name=,GIT_AUTHOR_*andGIT_COMMITTER_*. ACo-Authored-Bytrailer passes. - basics
rm-rootalso covers a folder directly in the home directory (~/Documents,~/Desktop; caches such as~/.cache,~/.npmand~/tmppass) and top-level folders of the drive (/srv,/usr). - New config keys
diskGuard.enabled,checkoutGuard.stageAll,checkoutGuard.removeSessionDirandbasics.agentAuthor, andBULKHEAD_DISABLEnamesdisk-guard,stage-all,remove-session-dirandagent-author.bulkhead doctorlists rules turned off in any guard. - The skill covers committing by file name, not deleting another session's folder, the git identity, and the disk.
Changed
- The repository moved to
dooly6276/claude-bulkhead; the old address redirects. Install with/plugin marketplace add dooly6276/claude-bulkhead. - New README hero and
bulkhead scananimations, light and dark.
0.1.1 - 2026-10-13
/bulkhead:remoteprinted nothing when no remote was configured, and/bulkhead:doctorprinted nothing when a check failed: Claude Code drops a slash command whose shell step exits non-zero. Both now show the output.- Each slash command pre-approves only the one
bulkheadcommand it runs instead of anynodecommand. - The repository no longer ships
package-lock.json. Claude Code installs a plugin's packages when it finds a lockfile in the plugin root, so the lint tools could be installed with the plugin. The runtime still has no dependencies. PRIVACY.mdlists what bulkhead reads, stores and sends, andplugin.jsoncarries the listing links.
0.1.0 - 2026-10-13
First public release.
Guards
- kill-guard blocks kills by program name that would hit other sessions' processes:
pkill,killall,taskkill /IMand/FI,Stop-Process -Name,Get-Process ... | Stop-Process,wmic ... delete, name lookups fed tokillthrough$(...),xargs, loops or variables, wildcards and several names at once. Kills scoped to a PID, a command line, a path or a script pass. - wait-guard blocks foreground waits that can hold a session longer than 180 seconds: sleep loops, inline
python -cornode -esleeps,timeout /t,ping -n,[Threading.Thread]::Sleep, and following a log withtail -f,docker logs -f,journalctl -forGet-Content -Wait. Sleeps in a background job pass. - memory-guard blocks heavy commands (test suites, builds, browser automation, container builds) when free RAM is below 3 GB or 15% of RAM, and points to
bulkhead-slotor, when one is configured,bulkhead remote. - port-guard blocks starting a dev server on a port another live session is listening on and suggests a free one. It also blocks kills by port aimed at another session's server (
npx kill-port,fuser -k,lsof -t -i:N | xargs kill,Get-NetTCPConnectionwithStop-Process,netstatwithtaskkill). - checkout-guard blocks
git checkout,switch,stash,reset --hard,clean -f,rebase,mergeand a dirtypullwhen another live session works in the same working tree, and suggestsgit worktree add. - basics blocks
rm -rfat roots, the home directory and folders above the repository, force-pushes to protected branches, andgit reset --hardorgit clean -fdthat would lose uncommitted work. Each rule can be turned off. - orphan-reaper stops what a finished session left running: dev servers, test runners and their workers (Vitest, Jest, Mocha, AVA,
node --test, Playwright, pytest and pytest-xdist,cargo test,go test,dotnet test), watchers, builders and automation browsers. It runs within seconds of a session exiting (a detached waiter started by theSessionEndhook) and again at session start. Only processes started from that session's Claude tool shells are touched; editors, terminals, shared build daemons and machine services are never stopped, nor anything under them. Windows, macOS and Linux.
All guards read commands through one shared parser for Bash, PowerShell and cmd that opens wrappers (bash -c, powershell -Command, -EncodedCommand, cmd /c, eval, sudo, env, timeout, xargs and more) up to three levels deep. Commit, tag, pull request and release text never triggers a guard. Commands sent to another machine or container are left to that machine.
Commands
bulkhead statusandbulkhead top: sessions with their project, memory, child processes and ports, slot jobs and the queue, free RAM, and the latest blocks.topis a live full-screen view.bulkhead-slot run --gb=N -- <command>(alsobulkhead slot): queues heavy commands against a RAM budget shared by every session on the machine.bulkhead remote(optional): runs a heavy command on another machine over SSH. It sends the commit as an incremental git bundle plus uncommitted changes, runs it in one of up to 8 copies of the repository with its own port inBULKHEAD_PORT, returns the exit code, and stops everything the command started when it ends or the connection drops.--tail=Nkeeps the full output in a file and prints only the end. Alsofetch,status,list,addandremove. The remote needs only an SSH server, bash, git and tar. Seedocs/remote.md.bulkhead reap [--dry-run]: runs orphan-reaper by hand; the dry run lists what it would stop and why.bulkhead log: what the guards blocked and what orphan-reaper stopped, with--since,--guard,--summaryand--json.bulkhead doctor: checks the install, the settings, each guard, the process reader, RAM limits, slots, the event log, git and configured remotes.bulkhead config: every setting, its effective value and where it came from.bulkhead port [--near N]: a port nothing listens on.bulkhead-statusline: live sessions, held slots and free RAM for the Claude Code status line.- Slash commands
/bulkhead:status,/bulkhead:log,/bulkhead:doctor,/bulkhead:remoteand/bulkhead:reap, and abulkheadskill that tells Claude how to work on a machine shared with other sessions.
Configuration
~/.claude/bulkhead/config.jsonand a per-project.claude/bulkhead.json, merged in that order, with environment variables winning. Every guard can be turned off, and the common false positives have their own keys. A broken file is ignored and reported once at session start. Remotes can be set in the global file only. Seeconfig.example.jsonanddocs/configuration.md.- Every block and every stopped process is appended to
events.jsonlin the state directory;BULKHEAD_NO_LOG=1turns it off.
Quality
- More than 2,400 tests on Linux, macOS and Windows with Node 18, 22 and 24, including a corpus of more than 900 real command lines run through the actual hooks, a fuzz test that checks every guard stays linear on 1 MB inputs, and an end-to-end
bulkhead remoterun against a real SSH server. - No dependencies. Each guard adds about 40 to 50 ms to a tool call.