Parallel development in tmux* with git worktrees

📖 Documentation · Install · Quick start · Commands · Changelog

Giga opinionated zero-friction workflow tool for managing git worktrees and tmux windows as isolated development environments. Perfect for running multiple AI agents in parallel without conflict.

Philosophy: Build on tools you already use. tmux/zellij/kitty/etc. for windowing, git for worktrees, your agent for coding - workmux ties them together.

^{_{* Also supports kitty, WezTerm, and Zellij as alternative backends.}}

📖 New to workmux? Read the introduction blog post for a quick overview.

_{Also from the author of workmux: aven, one queue for every project, with a keyboard-driven TUI for you and a CLI for your agents.}

Why workmux?

Parallel workflows. Work on multiple features the same time, each with its own AI agent. No stashing, no branch switching, no conflicts.

One window per task. A natural mental model. Each has its own terminal state, editor session, dev server, and AI agent. Context switching is switching tabs.

Automated setup. New worktrees start broken (no .env, no node_modules, no dev server). workmux can copy config files, symlink dependencies, and run install commands on creation.

One-command cleanup. workmux merge handles the full lifecycle: merge the branch, delete the worktree, close the tmux window, remove the local branch.

Terminal workflow. Build on your terminal setup instead of yet another agentic GUI that won't exist next year. If you don't have one yet, tmux might be worth picking up.

New to worktrees? See Why git worktrees?

Features

• Create git worktrees with matching tmux windows in a single command (add)
• Merge branches and clean up everything (worktree, tmux window, branches) in one command (merge)
• Dashboard for monitoring agents, reviewing changes, and sending commands
• Sidebar for a persistent, at-a-glance view of all agents across tmux windows
• Delegate tasks to worktree agents with the /worktree skill
• Display agent status in tmux window names
• Automatically set up your preferred tmux pane layout (editor, shell, watchers, etc.)
• Run post-creation hooks (install dependencies, setup database, etc.)
• Copy or symlink configuration files (.env, node_modules) into new worktrees
• Sandbox agents in containers or VMs for enhanced security
• Automatic branch name generation from prompts using LLM
• Shell completions

What people say

• "I've been using (and loving) workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow." - Coolin96 on Hacker News
• "Thank you so much for your work with workmux! It's a tool I've been wanting to exist for a long time." - rstacruz on GitHub
• "It's become my daily driver - the perfect level of abstraction over tmux + git, without getting in the way or obscuring the underlying tooling." - cisaacstern on GitHub
• "I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows." - dedbrizz on Threads
• "Since I discovered workmux I'm cooking. Amazing parallel-agent driver if you like tmux and want to keep your config." - MatijaSosic on X
• "Using workmux with a well-configured tmux has been a breath of fresh air" - sbeirakh_il on X
• "I've been using it for about a month now, and it's been nothing but great." - gabrielrockson_ on X
• "I still don't see the need for Herdr. Workmux adds busy/question/done status, manages worktrees by itself, and etc. It lives on an already existing tmux setup." - 13hcoks on X
• "workmux is fantastic. nothing too fancy, solves a real problem and stays in TMUX ❤️" - devopstoolbox on X
• "Workmux is fantastic if you're mostly terminal bound." - cody1786 on X
• "Want modern terminal workspace features without abandoning your setup? Here is how to keep Tmux and boost your workflow using Workmux." - Sam Natale on YouTube

Community videos

Some kind people have made videos about workmux on YouTube. If you're looking for a demo, check them out.

Tmux is Still Better Than Herdr (Here's Why) Sam Natale

I Don't Want a New Terminal. I Want THIS for Tmux. DevOps Toolbox

Tmux Didn't Need a Replacement, It Needed Workmux Seth Phaeno

Installation

Official sources: github.com/raine/workmux and workmux.dev. This project is not affiliated with workmux.com.

Bash YOLO

curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash

Homebrew (macOS/Linux)

brew install raine/workmux/workmux

cargo install workmux

mise use -g cargo:raine/workmux

nix profile install github:raine/workmux

For manual installation, see pre-built binaries.

Quick start

[!NOTE] workmux requires a terminal multiplexer. Make sure you have tmux (or WezTerm / Kitty / Zellij) installed and running before you start. See My tmux setup if you need a starting point.

1. Initialize configuration (optional):

bash workmux init

This creates a .workmux.yaml file to customize your workflow (pane layouts, setup commands, file operations, etc.). workmux works out of the box with sensible defaults, so this step is optional.

2. Create a new worktree and tmux window:

bash workmux add new-feature

This will: - Create a git worktree at <project_root>/../<project_name>__worktrees/new-feature - Copy config files and symlink dependencies (if configured) - Run any post_create setup commands - Create a tmux window named wm-new-feature (the prefix is configurable) - Set up your configured or the default tmux pane layout - Automatically switch your tmux client to the new window

3. Do your thing

4. Finish and clean up

Local merge: Run workmux merge to merge into the base branch and clean up in one step.

PR workflow: Push and open a PR. After it's merged, run workmux remove to clean up.

Configuration

workmux uses a two-level configuration system:

• Global (~/.config/workmux/config.yaml): Personal defaults for all projects
• Project (.workmux.yaml): Project-specific overrides

Project settings override global settings. When you run workmux from a subdirectory, it walks upward to find the nearest .workmux.yaml, allowing nested configs for monorepos. See the Monorepos guide for details. For hook lists (post_create, pre_merge, pre_remove) and file operation lists (files.copy, files.symlink), you can use "<global>" to include global values alongside project-specific ones. Other settings like panes are replaced entirely when defined in the project config.

Global configuration example

~/.config/workmux/config.yaml:

```yaml nerdfont: true # Enable nerdfont icons (prompted on first run) merge_strategy: rebase # Make workmux merge do rebase by default merge_keep: true # Keep worktree, window, and branch after merge by default confirm_unmerged_removal: false # Remove