dmux-workflows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dmux Workflows

dmux工作流

Orchestrate parallel AI agent sessions using dmux, a tmux pane manager for agent harnesses.

使用dmux（面向Agent工具的tmux面板管理器）编排并行AI Agent会话。

When to Activate

适用场景

Running multiple agent sessions in parallel
Coordinating work across Claude Code, Codex, and other harnesses
Complex tasks that benefit from divide-and-conquer parallelism
User says "run in parallel", "split this work", "use dmux", or "multi-agent"

并行运行多个Agent会话
跨Claude Code、Codex及其他工具协调工作
适合采用分治并行策略的复杂任务
用户提及"并行运行"、"拆分工作"、"使用dmux"或"多Agent"时

What is dmux

什么是dmux

dmux is a tmux-based orchestration tool that manages AI agent panes:

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

Install: Install dmux from its repository after reviewing the package. See github.com/standardagents/dmux

dmux是基于tmux的编排工具，用于管理AI Agent面板：

按
```
n
```
键创建带提示的新面板
按
```
m
```
键将面板输出合并回主会话
支持：Claude Code、Codex、OpenCode、Cline、Gemini、Qwen

安装：查看包内容后从其仓库安装dmux，详见github.com/standardagents/dmux

Quick Start

快速入门

bash

undefined

bash

undefined

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

undefined

undefined

Workflow Patterns

工作流模式

Pattern 1: Research + Implement

模式1：研究+实现

Split research and implementation into parallel tracks:

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."

将研究与实现拆分为并行任务线：

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

undefined

undefined

Pattern 2: Multi-File Feature

模式2：多文件功能开发

Parallelize work across independent files:

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"

并行处理独立文件的相关工作：

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

undefined

undefined

Pattern 3: Test + Fix Loop

模式3：测试+修复循环

Run tests in one pane, fix in another:

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"

在一个面板运行测试，另一个面板修复问题：

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"

Pattern 4: Cross-Harness

模式4：跨工具协作

Use different AI tools for different tasks:

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"

针对不同任务使用不同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"

Pattern 5: Code Review Pipeline

模式5：代码审查流水线

Parallel review perspectives:

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"

并行从多维度进行代码审查：

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

undefined

undefined

Best Practices

最佳实践

Independent tasks only. Don't parallelize tasks that depend on each other's output.
Clear boundaries. Each pane should work on distinct files or concerns.
Merge strategically. Review pane output before merging to avoid conflicts.
Use git worktrees. For file-conflict-prone work, use separate worktrees per pane.
Resource awareness. Each pane uses API tokens — keep total panes under 5-6.

仅处理独立任务：不要并行处理依赖彼此输出的任务。
明确边界：每个面板应负责不同的文件或关注点。
策略性合并：合并前先审查面板输出，避免冲突。
使用git worktree：对于易产生文件冲突的工作，为每个面板使用独立的worktree。
资源感知：每个面板会消耗API Token，建议并行面板数量控制在5-6个以内。

Git Worktree Integration

Git Worktree集成

For tasks that touch overlapping files:

bash

undefined

针对涉及重叠文件的任务：

bash

undefined

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

undefined

git merge feat/auth git merge feat/billing

undefined

Complementary Tools

配套工具

Tool	What It Does	When to Use
dmux	tmux pane management for agents	Parallel agent sessions
Superset	Terminal IDE for 10+ parallel agents	Large-scale orchestration
Claude Code Task tool	In-process subagent spawning	Programmatic parallelism within a session
Codex multi-agent	Built-in agent roles	Codex-specific parallel work

工具	功能	适用场景
dmux	面向Agent的tmux面板管理	并行Agent会话
Superset	支持10+并行Agent的终端IDE	大规模编排
Claude Code Task tool	进程内子Agent生成	会话内程序化并行处理
Codex multi-agent	内置Agent角色	Codex专属并行工作

ECC Helper

ECC辅助工具

ECC now includes a helper for external tmux-pane orchestration with separate git worktrees:

bash

node scripts/orchestrate-worktrees.js plan.json --execute

Example

plan.json

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." }
  ]
}

The helper:

Creates one branch-backed git worktree per worker
Optionally overlays selected
```
seedPaths
```
from the main checkout into each worker worktree

Writes per-worker

task.md

handoff.md

, and

status.md

files under

.orchestration/<session>/

Starts a tmux session with one pane per worker
Launches each worker command in its own pane
Leaves the main pane free for the orchestrator

Use

seedPaths

when workers need access to dirty or untracked local files that are not yet part of

HEAD

, such as local orchestration scripts, draft plans, or docs:

json

{
  "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." }
  ]
}

ECC现已支持通过独立git worktree进行外部tmux面板编排的辅助工具：

bash

node scripts/orchestrate-worktrees.js plan.json --execute

示例

plan.json

：

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." }
  ]
}

该辅助工具可：

为每个Worker创建一个基于分支的git worktree
可选将主 checkout中的指定
```
seedPaths
```
覆盖到每个Worker的worktree中

在

.orchestration/<session>/

目录下为每个Worker生成

task.md

、

handoff.md

和

status.md

文件

启动一个tmux会话，每个Worker对应一个面板
在各自面板中启动Worker命令
保留主面板供编排者使用

当Worker需要访问尚未提交到

HEAD

的本地脏文件或未跟踪文件（如本地编排脚本、草稿计划或文档）时，可使用

seedPaths

：

json

{
  "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." }
  ]
}

Troubleshooting

故障排除

Pane not responding: Switch to the pane directly or inspect it with
```
tmux capture-pane -pt <session>:0.<pane-index>
```
.
Merge conflicts: Use git worktrees to isolate file changes per pane.
High token usage: Reduce number of parallel panes. Each pane is a full agent session.
tmux not found: Install with
```
brew install tmux
```
(macOS) or
```
apt install tmux
```
(Linux).

面板无响应：直接切换到该面板，或使用
```
tmux capture-pane -pt <session>:0.<pane-index>
```
命令检查。
合并冲突：使用git worktree隔离每个面板的文件更改。
Token消耗过高：减少并行面板数量。每个面板对应一个完整的Agent会话。
未找到tmux：在macOS上用
```
brew install tmux
```
安装，Linux上用
```
apt install tmux
```
安装。