Skip to main content
Agent skill

Dmux Workflows

Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Dmux Workflows when an AI agent needs a reusable SKILL.md workflow for this job: Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.

When not to use it

Skip Dmux Workflows when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/dmux-workflows
# Save SKILL.md to ~/.claude/skills/dmux-workflows/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/dmux-workflows/SKILL.md. For a shared project, commit the folder at .claude/skills/dmux-workflows/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Dmux Workflows skill for this task: Use Dmux Workflows when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

76/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
85/100
Practical detail
76/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiinferred

    The skill text mentions Gemini or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# dmux Workflows

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

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

## What is 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](https://github.com/standardagents/dmux)

## Quick Start

```bash # 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 ```

## Workflow Patterns

### Pattern 1: Research + Implement

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

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

### Pattern 2: Multi-File Feature

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"

# Merge all, then do integration in main pane ```

### Pattern 3: Test + Fix Loop

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

### Pattern 4: Cross-Harness

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

### Pattern 5: Code Review Pipeline

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"

# Merge all reviews into a single report ```

## Best Practices

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

## Git Worktree Integration

For tasks that touch overlapping files:

```bash # 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 ```

## 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 |

## ECC Helper

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

```bash # Use the configured plugin root or standalone install (~/.claude or # $CLAUDE_CONFIG_DIR). For a reviewed and explicitly authorized ECC checkout: # export CLAUDE_PLUGIN_ROOT="/absolute/path/to/reviewed/ECC" ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}" [ -f "$ECC_ROOT/scripts/orchestrate-worktrees.js" ] || { echo "ECC scripts not found in the selected root (set CLAUDE_PLUGIN_ROOT to an authorized ECC checkout)" >&2; exit 1; } node "$ECC_ROOT/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." } ] } ```

## 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).

Intended uses

  • Use Dmux Workflows when this documented workflow matches the task.

Implementation notes

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

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.