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:

npm install -g dmux

or see github.com/standardagents/dmux

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

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

安装方式：

npm install -g dmux

或查看 github.com/standardagents/dmux

Quick Start

快速开始

bash

undefined

bash

undefined

Start dmux session

启动dmux会话

dmux

Create agent panes (press 'n' in dmux, then type prompt)

创建Agent面板（在dmux中按'n'键，然后输入提示）

Pane 1: "Implement the auth middleware in src/auth/"

面板1："在src/auth/中实现认证中间件"

Pane 2: "Write tests for the user service"

面板2："为用户服务编写测试用例"

Pane 3: "Update API documentation"

面板3："更新API文档"

Each pane runs its own agent session

每个面板运行独立的Agent会话

Press 'm' to merge results back

按'm'键合并结果

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

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

面板1（研究）："研究Node.js中限流的最佳实践。
  调研现有库，对比不同方案，并将研究结果写入
  /tmp/rate-limit-research.md"

面板2（实现）："为我们的Express API实现限流中间件。
  先从基础的令牌桶算法开始，研究完成后再进行优化。"

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

面板1完成后，将研究结果合并到面板2的上下文当中

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"

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

面板1："为计费功能创建数据库模式和迁移文件"
面板2："在src/api/billing/中构建计费API端点"
面板3："创建计费仪表盘UI组件"

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"

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

面板1（监控）："以监听模式运行测试套件。当测试失败时，
  总结失败原因。"

面板2（修复）："根据面板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工具：

面板1（Claude Code）："审查认证模块的安全性"
面板2（Codex）："重构工具函数以提升性能"
面板3（Claude Code）："为结账流程编写端到端测试"

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"

从多个维度并行审查：

面板1："审查src/api/中的安全漏洞"
面板2："审查src/api/中的性能问题"
面板3："审查src/api/中的测试覆盖率缺口"

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工作树：对于易产生文件冲突的工作，为每个面板使用独立的工作树。
资源意识：每个面板都会消耗API令牌——将面板总数控制在5-6个以内。

Git Worktree Integration

Git工作树集成

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

在独立工作树中运行Agent

Pane 1: cd ../feature-auth && claude

面板1：cd ../feature-auth && claude

Pane 2: cd ../feature-billing && claude

面板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_sh} --task-file {task_file_sh}",
  "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_sh}/scripts/orchestrate-codex-worker.sh {task_file_sh} {handoff_file_sh} {status_file_sh}",
  "workers": [
    { "name": "seed-check", "task": "Verify seeded files are present before starting work." }
  ]
}

ECC现在包含一个辅助工具，用于结合独立git工作树的外部tmux面板编排：

bash

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

示例

plan.json

：

json

{
  "sessionName": "skill-audit",
  "baseRef": "HEAD",
  "launcherCommand": "codex exec --cwd {worktree_path_sh} --task-file {task_file_sh}",
  "workers": [
    { "name": "docs-a", "task": "修复技能1-4并编写交接说明。" },
    { "name": "docs-b", "task": "修复技能5-8并编写交接说明。" }
  ]
}

该辅助工具：

为每个Worker创建一个基于分支的git工作树
可选地将主检出中的选定
```
seedPaths
```
覆盖到每个Worker的工作树中

在

.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_sh}/scripts/orchestrate-codex-worker.sh {task_file_sh} {handoff_file_sh} {status_file_sh}",
  "workers": [
    { "name": "seed-check", "task": "开始工作前验证种子文件是否存在。" }
  ]
}

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工作树隔离每个面板的文件更改。
令牌消耗过高：减少并行面板数量。每个面板都是一个完整的Agent会话。
未找到tmux：在macOS上使用
```
brew install tmux
```
安装，在Linux上使用
```
apt install tmux
```
安装。