<picture> <source media="(prefers-color-scheme: dark)" srcset="meta/logo-dark.svg"> <img src="meta/logo.svg" alt="workmux icon" width="300"> </picture> Parallel development in tmux* with git worktrees <a href="https://workmux.raine.dev/">📖 Documentation</a> · <a href="#installation">Install</a> · <a href="#quick-start">Quick start</a> · <a href="#commands">Commands</a> · <a href="CHANGELOG.md">Changelog</a>

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 orchestrates the rest.

* Also supports <a href="https://workmux.raine.dev/guide/kitty">kitty</a>, <a href="https://workmux.raine.dev/guide/wezterm">WezTerm</a>, and <a href="https://workmux.raine.dev/guide/zellij">Zellij</a> as alternative backends.

📚 See the full documentation for guides and configuration reference.

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

workmux demo

Why workmux?

Parallel workflows. Work on multiple features or hotfixes at 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
Delegate tasks to worktree agents with the /worktree skill
Display Claude 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

Hype

"I've been using (and loving) workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow."
— @Coolin96 🔗

"Thank you so much for your work with workmux! It's a tool I've been wanting to exist for a long time."
— @rstacruz 🔗

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

Installation

Bash YOLO

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

Homebrew (macOS/Linux)

brew install raine/workmux/workmux

Cargo

Requires Rust. Install via rustup if you don't have it.

cargo install workmux

Nix

nix profile install github:raine/workmux
# or try without installing
nix run github:raine/workmux -- --help

See Nix guide for flake and home-manager setup.

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.

Initialize configuration (optional):
```
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.
Create a new worktree and tmux window:
```
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
Do your thing
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 post_create 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:

nerdfont: true # Enable nerdfont icons (prompted on first run)
merge_strategy: rebase # Make workmux merge do rebase by default
agent: claude

panes:
  - command: <agent> # Start the configured agent (e.g., claude)
    focus: true
  - split: horizontal # Second pane with default shell

Project configuration example

.workmux.yaml:

post_create:
  - '<global>'
  - mise use

files:
  symlink:
    - '<global>' # Include global symlinks (node_modules)
    - .pnpm-store # Add project-specific symlink

panes:
  - command: pnpm install
    focus: true
  - command: <agent>
    split: horizontal
  - command: pnpm run dev
    split: vertical

For a real-world example, see workmux's own .workmux.yaml.

Configuration options

Most options have sensible defaults. You only need to configure what you want to customize.

Basic options

| Option | Description | Default | | ---------------- | ---------------------------------------------------- | ----------------------- | | main_branch | Branch to merge into | Auto-detected | | base_branch | Default base branch for new worktrees | Current branch | | worktree_dir | Directory for worktrees (absolute or relative) | <project>__worktrees/ | | window_prefix | Prefix for tmux window/session names | wm- | | mode | Tmux mode (window or session) | window | | agent | Default agent for <agent> placeholder | claude | | merge_strategy | Default merge strategy (merge, rebase, squash) | merge | | theme | Dashboard color scheme | default (auto dark/light) |

Naming options

| Option | Description | Default | | ----------------- | ------------------------------------------- | ------- | | worktree_naming | How to derive names from branches | full | | worktree_prefix | Prefix for worktree directories and windows | none |

worktree_naming strategies:

full: Use the full branch name (slashes become dashes)
basename: Use only the part after the last / (e.g., prj-123/feature → feature)

Panes

Define your tmux pane layout with the panes array. For multiple windows in session mode, use windows instead (they are mutually exclusive).

panes:
  - command: <agent>
    focus: true
  - command: npm run dev
    split: horizontal
    size: 15

Each pane supports:

| Option | Description | Default | | ------------ | -------------------------------------------------------------- | ------- | | command | Command to run (see [agent placeholders](#age

Workmux

Install / Use

README