단 한 번의 세션으로 모든 레포지토리에서 Claude 실행하기

claude-muster는 Claude Code를 위한 오케스트레이터 (orchestrator)입니다. 각 레포지토리의 .claude/를 있는 그대로 유지하면서 해당 레포지토리 내부에서 자체 Claude를 실행하며, 루트(root)에 있는 Claude가 어떤 작업이 누구에게 할당될지 결정합니다.

다음은 한 번의 세션에서 이루어지는 전체 과정입니다:

$ cd ~/work
$ claude-muster repos

...

해당 자식 프로세스는 api/ 내부에서 claude를 실행했습니다. 이는 마치 사용자가 직접 그곳에서 Claude를 연 것처럼, api의 실제 작업 디렉토리 (working directory), 환경 변수 (environment), 기술 (skills), 에이전트 (agents), 훅 (hooks), 그리고 권한 (permissions)을 그대로 사용합니다. 아무것도 복사되지 않았습니다. 아무것도 병합되지 않았습니다. 드리프트 (drift)되거나 정리해야 할 것도 없습니다.

이 도구가 해결하는 격차

여러 개의 개별 git 레포지토리로 구성된 하나의 폴더에 작업 내용이 들어있고, 각 레포지토리가 자체적인 .claude/를 가지고 있다고 가정해 봅시다:

~/work/
├── webapp/    → .claude/skills/deploy, .claude/commands/release
├── api/       → .claude/skills/lint, .claude/agents/db-reviewer, .claude/hooks/pre-commit
...

api/ 내부에서 Claude Code를 열면 api의 모든 툴링 (tooling)을 사용할 수 있습니다. 좋습니다. 하지만 세 곳 모두에서 동시에 작업하기 위해 ~/work/에서 Claude Code를 열면 그 툴링들이 사라집니다. 왜냐하면 Claude Code는 현재 폴더와 그 상위 폴더에서 .claude/를 읽을 뿐, 하위 폴더는 절대 읽지 않기 때문입니다.

명백한 해결책은 모든 것을 위로 끌어올리는 것입니다. 각 레포지토리의 .claude/를 ~/work/.claude/로 복사하거나 심볼릭 링크 (symlink)를 거는 것이죠. 기술 (skills)에 대해서는 작동하겠지만, 나머지 부분은 조용히 망가집니다:

• api/ 내부에서 실행되도록 작성된 훅 (hook)이 이제 잘못된 작업 디렉토리로 ~/work/에서 실행됩니다.
• 한 레포지토리의 deny 권한이 다른 모든 레포지토리를 조용히 차단합니다.
• API_URL을 설정하는 두 개의 레포지토리가 하나의 값으로 충돌합니다.
• 에이전트 (agents)를 복사해야 하므로, 소스가 변경되는 즉시 버전이 뒤처지게 됩니다.

결국 당신은 작업을 하는 대신 병합된 .claude/를 관리(babysitting)하게 됩니다.

claude-muster는 정반대의 접근 방식을 취합니다. 모든 레포지토리의 툴링(tooling)을 하나의 세션으로 끌어올리는 대신, 각 .claude/를 제자리에 두고 해당 레포지토리 내부에서 그 레포지토리만의 Claude를 실행합니다. 루트(root)에 있는 Claude는 디스패처(dispatcher)가 됩니다. 즉, 작업이 어떤 레포지토리에 속하는지 결정하고, 작업을 넘긴 뒤, 결과를 다시 읽어옵니다.

루트 Claude가 스스로 수행하도록 가르치기

dispatch를 직접 호출하는 것은 수동 기어와 같습니다. 라우팅(routing) 기술을 설치하면, 루트 Claude는 어떤 레포지토리에 접속해야 하는지 일일이 지시받지 않고도 위임(delegate)하는 법을 배웁니다:

$ claude-muster install     # ~/work/.claude/에 작은 기술(skill)을 추가합니다.

$ claude
...

기술이 작동할 때까지 기다리는 대신, 세션이 시작되는 즉시 루트 Claude가 자신의 레포지토리들을 알게 하고 싶나요? --hook을 추가하세요:

$ claude-muster install --hook    # SessionStart 후크도 함께 등록합니다.

이제 이곳의 모든 세션은 어떤 레포지토리로 작업을 보낼 수 있는지에 대한 한 줄 요약 브리핑과 함께 시작됩니다. 이 후크는 claude-muster가 settings.json에 쓰는 유일한 요소이며, uninstall을 실행하면 정확히 그것만 다시 제거합니다 — 파일에 다른 내용이 남아있지 않다면 파일 자체를 삭제합니다.

하나의 레포지토리, 또는 전체로 확산하기

dispatch <repo> "<task>"는 하나의 독립된 작업을 하나의 레포지토리로 보냅니다. 해당 레포지토리에서 새로 열린 Claude에게 말하듯 작성하세요. 왜냐하면 실제로 그렇기 때문입니다 — 자식(child) 프로세스는 루트 대화에 대한 기억 없이 시작됩니다.

dispatch --all "<task>"는 동일한 작업을 모든 레포지토리에 병렬로 보내고 결과를 수집합니다. 이는 설문 조사나 전수 조사(sweeps)를 위해 만들어졌습니다:

$ claude-muster dispatch --all --json "테스트 명령어가 무엇인가요?"
[
  { "repo": "webapp", "ok": true,  "text": "npm test", "code": 0 },
...

"어딘가에 인증(auth)에 관한 TODO가 있나요?", "버전을 2.0으로 올리세요" — 모두 같은 방식입니다. 답변을 직접 집계하고 싶을 때는 --json과 함께 사용하세요.

기본적으로 .claude/가 있는 모든 형제 레포지토리(sibling repo)가 포함됩니다. 루트(root)에 claude-muster.json을 추가하여 범위를 좁힐 수 있습니다:

{
  "include": ["webapp", "api/*", "services/**"],   // globs, 루트 기준 상대 경로
  "exclude": ["legacy-*"]
...

작동 원리

Claude Code는 각 레포지토리 자체 폴더와 그 상위 폴더에서 각 레포지토리의 .claude/를 읽습니다. claude-muster는 이를 방해하지 않습니다. 단지 자식 레포지토리를 작업 디렉토리(working directory)로 하여 claude를 실행할 뿐입니다:

자식 프로세스는 자체 레포지토리에 루트를 둔 실제 claude 프로세스이기 때문에, 모든 것을 병합하는 방식(merge-it-all approach)이 만들어내는 모든 문제들이 단순히 발생하지 않습니다. 작업 디렉토리가 정확하고, 훅(hooks)과 권한이 범위 내로 유지되며, 에이전트(agents)가 절대 오래되지 않고, 환경(environments)이 충돌하지 않으며, 정리할 것도 없습니다.

신뢰해도 안전한 이유

README에서 가장 중요한 문장은 이것입니다: claude-muster는 스스로 LLM을 호출하지 않습니다. dispatch는 Claude Code의 문서화된 헤드리스 모드(claude -p)에서 사용자의 Anthropic 인증과 사용자의 지갑으로 실행되는 로컬 claude CLI를 실행합니다. 자체 API 키도, 네트워크도, 텔레메트리(telemetry)도 없습니다. claude-muster는 작업을 어디로 보낼지 결정하고 돌아오는 결과물을 수집할 뿐입니다.

또한 디스크를 거의 건드리지 않습니다. dispatch와 repos는 레포지토리를 찾기 위해 폴더를 _읽기(read)_만 합니다. 유일하게 쓰는 것은 install 시의 라우팅 스킬(routing skill)뿐이며(선택 사항인 SessionStart 훅 포함), uninstall은 정확히 그것만을 제거합니다.

아직 지원하지 않는 기능

다음 사항들을 인지하고 사용하시길 권장합니다:

• 지속적인 자식 세션 (Persistent child sessions). 각 dispatch는 새로운 단발성 claude -p 실행이므로, 자식 세션은 이전에 보낸 작업을 기억하지 못합니다. 레포지토리별로 유지되는 따뜻한(warm), 장기 실행 세션은 향후 계획된 후속 기능입니다.
• 다른 머신의 레포지토리. 로컬 파일 시스템 내의 어디든 작동하지만 (paths 참조), 원격 또는 네트워크상의 레포지토리는 지원하지 않습니다.
• 모호할 때 추측하기. 작업이 여러 레포지토리에 속할 수 있는 경우, 라우팅 기능은 추측하기보다 질문하도록 설계되었습니다.

실용적인 참고 사항 하나: dispatch --all은 여러 개의 claude 프로세스를 동시에 시작하므로, 너무 광범위하게 확장할 경우 Anthropic의 속도 제한 (rate limits)에 걸릴 수 있습니다. 동시성 (concurrency)을 적절하게 유지하세요.

설치 (Install)

아직 npm에는 등록되지 않았습니다. 현재는 클론(clone)하여 빌드하세요:

git clone https://github.com/mk668a/claude-muster
cd claude-muster
npm install && npm run build
...

Node 18+ 버전이 필요합니다. 또한 dispatch가 실행할 claude CLI가 PATH에 설정되어 있어야 합니다. npm link를 사용하고 싶지 않다면, 빌드된 파일을 직접 호출하세요: node /path/to/claude-muster/dist/cli.js.

레포지토리: https://github.com/mk668a/claude-muster · MIT.

이 도구의 핵심은 한 문장으로 요약됩니다: 모든 사람의 .claude/를 하나의 세션으로 병합하는 것을 중단하고, 각 레포지토리의 Claude가 자신의 폴더에서, 자신의 도구들을 온전히 유지한 채 각자의 작업을 수행하도록 하세요. 병합 방식 때문에 어려움을 겪었던 워크스페이스에서 이 도구를 실행해 보신다면, 다섯 가지 충돌 중 어떤 것을 가장 먼저 조용히 해결했는지 꼭 듣고 싶습니다.