| name | dmux-workflows |
| description | dmux(AI 에이전트용 tmux 창 관리자)를 사용한 다중 에이전트 오케스트레이션. Claude Code, Codex, OpenCode 및 기타 하네스 전반에 걸친 병렬 에이전트 워크플로우 패턴. 여러 에이전트 세션을 병렬로 실행하거나 다중 에이전트 개발 워크플로우를 조정할 때 사용하세요. |
| origin | ECC |
dmux 워크플로우 (dmux Workflows)
에이전트 하네스용 tmux 창 관리자인 dmux를 사용하여 병렬 AI 에이전트 세션을 오케스트레이션합니다.
활성화 시점
- 여러 에이전트 세션을 병렬로 실행할 때
- Claude Code, Codex 및 기타 하네스 간의 작업을 조정할 때
- 분할 정복(divide-and-conquer) 방식의 병렬 처리가 도움이 되는 복잡한 작업 시
- 사용자가 "병렬로 실행해 줘", "이 작업을 나눠 줘", "dmux 사용해", 또는 "다중 에이전트"라고 말할 때
dmux란 무엇인가
dmux는 AI 에이전트 창(pane)을 관리하는 tmux 기반 오케스트레이션 도구입니다:
n을 눌러 프롬프트와 함께 새 창 생성m을 눌러 창의 출력을 메인 세션으로 병합- 지원: Claude Code, Codex, OpenCode, Cline, Gemini, Qwen
설치: 패키지 검토 후 해당 저장소에서 dmux를 설치하세요. github.com/standardagents/dmux 참조.
빠른 시작
dmux
워크플로우 패턴
패턴 1: 조사 + 구현 (Research + Implement)
조사와 구현을 병렬 트랙으로 나눕니다:
창 1 (조사): "Node.js에서의 속도 제한(rate limiting) 모범 사례를 조사해 줘.
현재 라이브러리들을 확인하고 방식을 비교해서 결과를
/tmp/rate-limit-research.md에 작성해 줘."
창 2 (구현): "우리 Express API를 위한 속도 제한 미들웨어를 구현해 줘.
기본적인 토큰 버킷 방식으로 시작해. 조사가 완료되면 세부 조정할 거야."
# 창 1이 완료된 후, 조사 결과를 창 2의 컨텍스트로 병합합니다.
패턴 2: 다중 파일 기능 (Multi-File Feature)
독립적인 파일들에 걸쳐 작업을 병렬화합니다:
창 1: "빌링 기능을 위한 데이터베이스 스키마와 마이그레이션을 생성해 줘"
창 2: "src/api/billing/에 빌링 API 엔드포인트를 구축해 줘"
창 3: "빌링 대시보드 UI 컴포넌트를 생성해 줘"
# 모두 병합한 다음, 메인 창에서 통합 작업을 수행합니다.
패턴 3: 테스트 + 수정 루프 (Test + Fix Loop)
한 창에서 테스트를 실행하고 다른 창에서 수정합니다:
창 1 (감시자): "테스트 스위트를 감시(watch) 모드로 실행해. 테스트가 실패하면
실패 내용을 요약해 줘."
창 2 (수정자): "창 1의 에러 출력을 바탕으로 실패한 테스트를 수정해 줘"
패턴 4: 크로스 하네스 (Cross-Harness)
작업별로 다른 AI 도구를 사용합니다:
창 1 (Claude Code): "인증 모듈의 보안을 검토해 줘"
창 2 (Codex): "성능을 위해 유틸리티 함수들을 리팩터링해 줘"
창 3 (Claude Code): "결제 플로우를 위한 E2E 테스트를 작성해 줘"
패턴 5: 코드 리뷰 파이프라인 (Code Review Pipeline)
병렬 리뷰 관점:
창 1: "src/api/의 보안 취약점을 리뷰해 줘"
창 2: "src/api/의 성능 이슈를 리뷰해 줘"
창 3: "src/api/의 테스트 커버리지 부족을 리뷰해 줘"
# 모든 리뷰를 하나의 보고서로 병합합니다.
모범 사례
- 독립적인 작업만 병렬화. 서로의 출력에 의존하는 작업은 병렬화하지 마세요.
- 명확한 경계. 각 창은 서로 다른 파일이나 관심사를 다뤄야 합니다.
- 전략적 병합. 충돌을 피하기 위해 병합 전에 창의 출력을 검토하세요.
- git worktree 사용. 파일 충돌 가능성이 높은 작업의 경우 창마다 별도의 worktree를 사용하세요.
- 리소스 인식. 각 창은 API 토큰을 사용하므로 전체 창 개수를 5~6개 이하로 유지하세요.
Git Worktree 통합
중복되는 파일을 건드리는 작업의 경우:
git worktree add -b feat/auth ../feature-auth HEAD
git worktree add -b feat/billing ../feature-billing HEAD
git merge feat/auth
git merge feat/billing
보완 도구
| 도구 | 역할 | 사용 시기 |
|---|
| dmux | 에이전트용 tmux 창 관리 | 병렬 에이전트 세션 |
| Superset | 10개 이상의 병렬 에이전트를 위한 터미널 IDE | 대규모 오케스트레이션 |
| Claude Code Task 도구 | 프로세스 내 하위 에이전트 생성 | 세션 내 프로그램 방식의 병렬 처리 |
| Codex 다중 에이전트 | 내장 에이전트 역할 | Codex 전용 병렬 작업 |
ECC 헬퍼 (ECC Helper)
ECC는 이제 별도의 git worktree를 사용하는 외부 tmux 창 오케스트레이션을 위한 헬퍼를 포함합니다:
node scripts/orchestrate-worktrees.js plan.json --execute
plan.json 예시:
{
"sessionName": "skill-audit",
"baseRef": "HEAD",
"launcherCommand": "codex exec --cwd {worktree_path} --task-file {task_file}",
"workers": [
{ "name": "docs-a", "task": "기술 1~4번을 수정하고 핸드오프 노트를 작성해 줘." },
{ "name": "docs-b", "task": "기술 5~8번을 수정하고 핸드오프 노트를 작성해 줘." }
]
}
헬퍼의 역할:
- 작업자당 하나의 브랜치 기반 git worktree 생성
- 선택적으로 메인 체크아웃의
seedPaths를 각 작업자 worktree에 덮어씌움
- 작업자별
task.md, handoff.md, status.md 파일을 .orchestration/<session>/ 아래에 생성
- 작업자당 하나의 창이 있는 tmux 세션 시작
- 각 창에서 해당 작업자 명령어 실행
- 메인 창은 오케스트레이터를 위해 비워둠
작업자가 로컬 오케스트레이션 스크립트, 초안 계획 또는 문서와 같이 아직 HEAD에 포함되지 않은 수정되거나 추적되지 않은 로컬 파일에 액세스해야 할 때 seedPaths를 사용하세요:
{
"sessionName": "workflow-e2e",
"seedPaths": [
"scripts/orchestrate-worktrees.js",
"scripts/lib/tmux-worktree-orchestrator.js",
".claude/plan/workflow-e2e-test.json"
],
"launcherCommand": "bash {repo_root}/scripts/orchestrate-codex-worker.sh {task_file} {handoff_file} {status_file}",
"workers": [
{ "name": "seed-check", "task": "작업 시작 전에 시드된 파일들이 있는지 확인해 줘." }
]
}
문제 해결
- 창이 응답하지 않음: 해당 창으로 직접 전환하거나
tmux capture-pane -pt <session>:0.<pane-index>로 검사하세요.
- 병합 충돌: 창별 파일 변경 사항을 격리하기 위해 git worktree를 사용하세요.
- 높은 토큰 사용량: 병렬 창 개수를 줄이세요. 각 창은 전체 에이전트 세션입니다.
- tmux를 찾을 수 없음:
brew install tmux(macOS) 또는 apt install tmux(Linux)로 설치하세요.
