dmux-workflows

name	dmux-workflows
description	dmux(AI 에이전트용 tmux pane 관리자)를 사용한 멀티 에이전트 오케스트레이션 패턴입니다. Claude Code, Codex, OpenCode 등 여러 하니스에서 병렬 에이전트 워크플로를 구성할 때 사용합니다.
origin	ECC

dmux 워크플로

에이전트 하니스를 위한 tmux pane 관리자인 dmux를 사용해 병렬 AI 에이전트 세션을 오케스트레이션합니다.

사용 시점

• 여러 에이전트 세션을 병렬로 실행할 때
• Claude Code, Codex, 기타 하니스 간 작업을 조정할 때
• 분할 정복식 병렬화가 유리한 복잡한 작업일 때
• 사용자가 "run in parallel", "split this work", "use dmux", "multi-agent"라고 말할 때

dmux란

dmux는 AI 에이전트 pane을 관리하는 tmux 기반 오케스트레이션 도구입니다.

• Press n to create a new pane with a prompt
• Press m to merge pane output back to the main session
• Supports: Claude Code, Codex, OpenCode, Cline, Gemini, Qwen

설치: 패키지를 검토한 뒤 저장소에서 dmux를 설치합니다. github.com/standardagents/dmux 참조

빠른 시작

# Start dmux session
dmux

# Create agent panes (press 'n' in dmux, then type prompt)
# Pane 1: "Implement the auth middleware in src/auth/"
# Pane 2: "Write tests for the user service"
# Pane 3: "Update API documentation"

# Each pane runs its own agent session
# Press 'm' to merge results back

워크플로 패턴

패턴 1: 조사 + 구현

조사와 구현을 병렬 트랙으로 분리합니다.

Pane 1 (Research): "Research best practices for rate limiting in Node.js.
  Check current libraries, compare approaches, and write findings to
  /tmp/rate-limit-research.md"

Pane 2 (Implement): "Implement rate limiting middleware for our Express API.
  Start with a basic token bucket, we'll refine after research completes."

# After Pane 1 completes, merge findings into Pane 2's context

패턴 2: 다중 파일 기능 작업

독립적인 파일 단위로 작업을 병렬화합니다.

Pane 1: "Create the database schema and migrations for the billing feature"
Pane 2: "Build the billing API endpoints in src/api/billing/"
Pane 3: "Create the billing dashboard UI components"

# Merge all, then do integration in main pane

패턴 3: 테스트 + 수정 루프

한 pane에서 테스트를 돌리고 다른 pane에서 수정합니다.

Pane 1 (Watcher): "Run the test suite in watch mode. When tests fail,
  summarize the failures."

Pane 2 (Fixer): "Fix failing tests based on the error output from pane 1"

패턴 4: 크로스 하니스

작업 성격에 따라 서로 다른 AI 도구를 사용합니다.

Pane 1 (Claude Code): "Review the security of the auth module"
Pane 2 (Codex): "Refactor the utility functions for performance"
Pane 3 (Claude Code): "Write E2E tests for the checkout flow"

패턴 5: 코드 리뷰 파이프라인

서로 다른 리뷰 관점을 병렬로 실행합니다.

Pane 1: "Review src/api/ for security vulnerabilities"
Pane 2: "Review src/api/ for performance issues"
Pane 3: "Review src/api/ for test coverage gaps"

# Merge all reviews into a single report

모범 사례

1. 독립 작업만 병렬화. 서로 출력에 의존하는 작업은 병렬화하지 않습니다.
2. 경계 명확화. 각 pane은 서로 다른 파일이나 관심사를 맡아야 합니다.
3. 전략적으로 병합. 충돌을 피하려면 병합 전에 pane 출력을 검토합니다.
4. git worktree 사용. 파일 충돌 가능성이 크면 pane별로 별도 worktree를 둡니다.
5. 리소스 인식. 각 pane은 API 토큰을 사용하므로 총 pane 수는 5~6개 이하로 유지합니다.

Git Worktree 연동

서로 겹치는 파일을 건드리는 작업이라면:

# Create worktrees for isolation
git worktree add -b feat/auth ../feature-auth HEAD
git worktree add -b feat/billing ../feature-billing HEAD

# Run agents in separate worktrees
# Pane 1: cd ../feature-auth && claude
# Pane 2: cd ../feature-billing && claude

# Merge branches when done
git merge feat/auth
git merge feat/billing

함께 쓰기 좋은 도구

Tool	What It Does	When to Use
dmux	에이전트용 tmux pane 관리	병렬 에이전트 세션
Superset	10개 이상 병렬 에이전트를 위한 터미널 IDE	대규모 오케스트레이션
Claude Code Task tool	프로세스 내부 서브에이전트 실행	세션 내부 프로그래매틱 병렬화
Codex multi-agent	내장 에이전트 역할	Codex 전용 병렬 작업

ECC 헬퍼

ECC에는 별도 git worktree를 사용하는 외부 tmux pane 오케스트레이션 헬퍼가 포함되어 있습니다.

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": "Fix skills 1-4 and write handoff notes." },
    { "name": "docs-b", "task": "Fix skills 5-8 and write handoff notes." }
  ]
}

이 헬퍼는 다음을 수행합니다.

• 워커별로 브랜치 기반 git worktree 1개 생성
• 필요하면 메인 체크아웃의 seedPaths를 각 워커 worktree에 오버레이
• .orchestration/<session>/ 아래에 워커별 task.md, handoff.md, status.md 파일 작성
• 워커당 pane 1개가 있는 tmux 세션 시작
• 각 워커 명령을 자기 pane에서 실행
• 메인 pane은 오케스트레이터용으로 비워 둠

워크가 아직 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": "Verify seeded files are present before starting work." }
  ]
}

문제 해결

• Pane 응답 없음: 해당 pane으로 직접 이동하거나 tmux capture-pane -pt <session>:0.<pane-index>로 상태를 확인합니다.
• 병합 충돌: pane별로 git worktree를 분리해 파일 변경을 격리합니다.
• 토큰 사용량 과다: 병렬 pane 수를 줄입니다. 각 pane은 완전한 에이전트 세션입니다.
• tmux 없음: macOS는 brew install tmux, Linux는 apt install tmux로 설치합니다.