Parallel agents with tmux and worktrees
Manage multiple AI coding agents in isolated git worktrees.
Branch, develop, and merge — all in parallel.
Documentation · Getting Started · Issues
Install
npm install -g dmux
Quick Start
cd /path/to/your/project
dmux
Press n to create a new pane, type a prompt, pick one or more agents (or none for a plain terminal), and dmux handles the rest — worktree, branch, and agent launch.
On first run, dmux can configure a primary inference provider/model and an optional backup. It discovers models from the provider when possible and supports API-key providers, custom OpenAI-compatible endpoints, a Codex login backed by your ChatGPT subscription, or a Grok Build login backed by your SpaceXAI subscription. Reopen the flow with s → Inference Providers.
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 a task is done, open the pane menu with m and choose Merge to bring it back into your main branch, or Create GitHub PR to push the branch and file a pull request.
- Worktree isolation — each pane is a full working copy, no conflicts between agents
- Agent support — Claude Code, Codex, OpenCode, Cline CLI, Gemini CLI, Qwen CLI, Amp CLI, pi CLI, Cursor CLI, Copilot CLI, and Crush CLI
- Goal launches — optionally start supported agents in goal mode from the initial prompt
- Multi-select launches — choose any combination of enabled agents per prompt
- AI naming — branches, commit messages, and active terminal panes named automatically
- Durable terminals — regular terminals restore in their last observed directory; if Codex, Claude, or another supported agent was running, dmux tracks it and resumes that conversation when the pane is recreated
- Smart merging — auto-commit, merge, and clean up in one step
- macOS notifications — background panes can send native attention alerts when they settle and need you, with a global off switch
- Built-in file browser — inspect a pane's worktree, search files, and preview code or diffs without leaving dmux
- Pane visibility controls — hide individual panes, isolate one project, or restore everything later without stopping work
- Multi-project — add multiple repos to the same session
- Lifecycle hooks — run scripts on worktree create, pre-merge, post-merge, and more
Git Branch Controls
dmux can use default branch behavior or let you override branch details when creating a pane.
- Keep the default flow for fast creation, where dmux automatically picks the worktree and git branch names.
- Optionally choose a different base branch per pane.
- Optionally provide an explicit branch/worktree name (useful for issue-tracker ticket naming).
- Multi-agent launches still use shared naming with agent-specific suffixes.
Keyboard Shortcuts
| Key | Action |
|---|---|
n |
New pane (worktree + agent) |
t |
New terminal pane |
j / Enter |
Jump to pane |
m |
Open pane menu |
f |
Browse files in selected pane's worktree |
x |
Close pane |
h |
Hide/show selected pane |
H |
Hide/show all other panes |
p |
New pane in another project |
P |
Show only the selected project's panes, then show all |
s |
Settings |
q |
Quit |
Requirements
- tmux 3.0+
- Node.js 18+
- Git 2.20+
- At least one supported agent CLI (for example Claude Code, Codex, Grok Build, OpenCode, Cline CLI, Gemini CLI, Qwen CLI, Amp CLI, pi CLI, Cursor CLI, Copilot CLI, Crush CLI)
- An inference provider API key, a Codex CLI login backed by a ChatGPT subscription, or a Grok Build CLI login backed by a SpaceXAI subscription (optional, for AI naming, summaries, and pane analysis)
Documentation
Full documentation is available at dmux.ai, including setup guides, configuration, and hooks.
Contributing
See CONTRIBUTING.md for the recommended local "dmux-on-dmux" development loop, hook setup, and PR workflow.
License
MIT