dmux-workflows

# 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:** `npm install -g dmux` or 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 ../feature-auth feat/auth git worktree add ../feature-billing feat/billing # 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 | ## Troubleshooting - **Pane not responding:** Check if the agent session is waiting for input. Use `m` to read output. - **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).