dmux: Parallel Agents with tmux and Worktrees

Source: GitHub | Website Author: Justin Schroeder (@jpschroeder) License: MIT | Version: 5.1.0

---

What It Does

dmux creates a tmux pane for each task. Every pane gets its own git worktree and branch so agents work in complete isolation. When done, press m to merge back into main.

• Worktree isolation -- each pane is a full working copy, no conflicts between agents
• Agent support -- Claude Code, Codex, OpenCode
• A/B launches -- run two agents on the same prompt side-by-side
• AI naming -- branches and commit messages generated automatically
• Smart merging -- auto-commit, merge, and clean up in one step
• Multi-project -- add multiple repos to the same session
• Lifecycle hooks -- scripts on worktree create, pre-merge, post-merge, etc.

Quick Start

npm install -g dmux
cd /path/to/your/project
dmux

Press n to create a new pane, type a prompt, pick an agent.

Architecture

+------------------------------------------+
|            User Interface                |
|         (Ink React TUI)                  |
+------------------------------------------+
|           Core Application               |
|         (TypeScript/Node.js)             |
+------------------------------------------+
|           External Services              |
|   (tmux, git, OpenRouter API)            |
+------------------------------------------+

Worktree Layout

main-project/
  .git/
  src/
  .dmux/
    dmux.config.json
    worktrees/
      fix-bug/         # Worktree for "fix bug" pane
      add-feature/     # Worktree for "add feature" pane

Pane Lifecycle

1. Create: generate slug -> create worktree -> split tmux pane -> launch agent with --permission-mode=acceptEdits
2. Auto-Cleanup: polls every 2s, removes dead panes
3. Merge: AI-generated commit -> merge to main -> remove worktree -> optional pane close

Hooks System

Hooks are executable scripts in .dmux/hooks/:

Hook	When
before_pane_create	Before pane creation
worktree_created	After worktree + agent launch
pre_merge	After user confirms merge, before merge op
post_merge	After successful merge
run_test	User triggers test
run_dev	User triggers dev server

Environment variables: DMUX_ROOT, DMUX_PANE_ID, DMUX_SLUG, DMUX_PROMPT, DMUX_AGENT, DMUX_WORKTREE_PATH, DMUX_BRANCH, etc.

Web Dashboard & API

• GET /api/panes -- list all panes with status
• POST /api/panes -- create new pane ({prompt, agent?})
• GET /api/panes-stream -- SSE real-time updates
• GET /api/stream/:id -- SSE terminal output
• POST /api/keys/:id -- send keystrokes

Merge Conflict Resolution

2-phase strategy:

1. Merge main -> worktree (detect conflicts in isolation)
2. Merge worktree -> main (bring changes back)

AI-assisted option: conflict resolution pane is created, agent resolves, auto-closes on completion.

Status Detection

LLM-based (grok-4-fast:free) analysis of terminal content:

• option_dialog, open_prompt, in_progress
• Key indicator: "(esc to interrupt)" = agent working
• One worker thread per pane, polls every 1s