Show GN: claude-bulkhead: PC에서 병렬로 돌리는 Claude Code 세션들의 프로세스, 포트, 메모리 충돌을 막는 플...

GitHub README(Myeongseok-Kang/claude-bulkhead)의 앞부분(소개, 필요성)을 옮겼어요. 설치·가드 상세·FAQ는 다루지 못했어요.

무엇인가

Hooks that stop parallel Claude Code sessions on one machine from killing each other's servers or running it out of RAM.

Claude Code 훅은 셸 명령 실행 전처럼 정해진 시점에 Claude Code가 돌리는 작은 프로그램으로, 명령을 막고 이유를 Claude에게 알려 줄 수 있어요. bulkhead는 여러 세션과 서브에이전트가 같은 컴퓨터에서 동시에 일하는 상황을 위한 훅 모음이에요. 가드 7개, 명령 9개, 상태 줄, 슬래시 명령 5개, 스킬 1개로 구성되고 의존성이 없어요.

각 세션은 기계를 혼자 쓰는 것처럼 행동해요. bulkhead는 셸 명령마다 다른 세션 상황(어떤 프로세스·포트가 어느 세션 것인지, 남은 RAM, 각 세션의 git 트리)을 확인하고, 다른 세션을 해칠 명령이면 막고 더 안전한 명령을 제안해요.

필요한 경우: 세션 두 개 이상을 동시에(흔히 worktree마다 하나) 돌리고, 세션·서브에이전트가 dev 서버, 빌드, 테스트를 띄울 때. 한 번에 한 세션만 쓰고 서버를 안 띄우면 필요 없을 거래요.

막아 주는 상황

| bulkhead 없이 | bulkhead와 함께 | |---|---| | pkill node로 재시작하다 다른 worktree 서버까지 다 죽음 | kill-guard가 막고 자기 PID만 찾아 끄는 법을 알려 줌 | | 두 번째 npm run dev가 3001로 옮겨 갔는데 에이전트는 3000을 테스트 | port-guard가 막고 빈 포트를 알려 줌(bulkhead port) | | 세 세션이 같은 분에 빌드·테스트·Playwright를 돌려 기계가 멈춤 | memory-guard가 RAM 부족 시 무거운 명령을 막고, bulkhead-slot으로 대기열에 넣음 | | 다른 세션이 편집 중인 트리에서 브랜치 체크아웃 | checkout-guard가 막고 git worktree add 제안 | | 세션이 끝나도 dev 서버·워커가 남아 RAM·포트 점유 | orphan-reaper가 몇 초 안에 정리 | | 서브에이전트가 10분간 포그라운드 폴링 | wait-guard가 막고 run_in_background: true 요청 |

왜 만들었나

한 저장소에 worktree별로 세션을 여러 개 돌리는 게 흔한 가속 방법인데, git은 브랜치를 나눠 주지만 기계는 포트·프로세스 테이블·RAM을 공유해요. 그래서 충돌해요. Claude Code 이슈 트래커에는 이런 사례가 많대요.

• dev 서버 재시작을 시켰더니 pkill node로 자기 세션까지 죽임(#13941)
• 손대지 말라고 한 PID인데 taskkill //F //IM python.exe로 장시간 시뮬레이션 두 개를 죽임(#34754)
• 봇 하나 재시작을 시켰더니 Python 프로세스 약 20개 서비스를 전부 강제 종료(#43225)
• 서브에이전트 24개가 4GB VPS를 포화시켜 재부팅(#15487)
• 에이전트가 띄운 프로세스가 남아 Node 60개, pytest 워커 550개가 남은 보고(#11502, #25180)