workmux

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.

[!TIP] consult-llm pairs naturally with workmux: let your agents consult another AI model to plan architecture, review changes, debate approaches, or get unstuck on tricky bugs without leaving the worktree.

See How to orchestrate large coding tasks without context bloat for a workflow that combines workmux and consult-llm.

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

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 🔗

"I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows."
— @dedbrizz 🔗

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 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):

   copy

   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:

   copy

   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 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
merge_keep: true # Keep worktree, window, and branch after merge 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

Naming options

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:

Agent placeholders

• <agent>: resolves to the configured agent (from agent config or --agent flag)

Built-in agents (claude, gemini, codex, opencode, kiro-cli, vibe, pi, omp) are auto-detected when used as literal commands and receive prompt injection automatically, without needing the <agent> placeholder or a matching agent config:

panes:
  - command: 'claude --dangerously-skip-permissions'
    focus: true
  - command: 'codex --yolo'
    split: vertical

Each agent receives the prompt (via -p/-P/-e) using the correct format for that agent. Auto-detection matches the executable name regardless of flags or path.

Named layouts

Define reusable pane arrangements in the layouts map and select one at add-time with -l/--layout:

layouts:
  design:
    panes:
      - command: <agent>
        focus: true
      - command: <agent:codex>
        split: vertical
  review:
    panes:
      - command: <agent>

workmux add my-feature -l design

When -l is used, the layout's panes replace the top-level panes for that worktree. All other config (hooks, files, agent, etc.) comes from the top-level as usual. The -l flag cannot be combined with --agent.

File operations

New worktrees are clean checkouts with no gitignored files (.env, node_modules, etc.). Use files to automatically copy or symlink what each worktree needs:

files:
  copy:
    - .env
  symlink:
    - .next/cache # Share build cache across worktrees

Both copy and symlink accept glob patterns.

To re-apply file operations to an existing worktree (e.g., after updating the config), run workmux sync-files from inside the worktree. Use --all to sync all worktrees at once.

Lifecycle hooks

Run commands at specific points in the worktree lifecycle, such as installing dependencies or running database migrations. All hooks run with the worktree directory as the working directory (or the nested config directory for nested configs) and receive environment variables: WM_HANDLE, WM_WORKTREE_PATH, WM_PROJECT_ROOT, WM_CONFIG_DIR.

WM_CONFIG_DIR points to the directory containing the .workmux.yaml that was used, which may differ from WM_WORKTREE_PATH when using nested configs.

Example:

post_create:
  - direnv allow

pre_merge:
  - just check

Agent status icons

Customize the icons shown in tmux window names:

status_icons:
  working: '🤖' # Agent is processing
  waiting: '💬' # Agent needs input (auto-clears on focus)
  done: '✅' # Agent finished (auto-clears on focus)

Agents in "working" status that produce no pane output for 10 seconds are automatically detected as interrupted.

Set status_format: false to disable automatic tmux format modification

Default behavior

• Worktrees are created in <project>__worktrees as a sibling directory to your project by default
• If no panes configuration is defined, workmux provides opinionated defaults:
  • For projects with a CLAUDE.md file: Opens the configured agent (see agent option) in the first pane, defaulting to claude if none is set.
  • For all other projects: Opens your default shell.
  • Both configurations include a second pane split horizontally
• post_create commands are optional and only run if you configure them

Automatic setup with panes

Use the panes configuration to automate environment setup. Unlike post_create hooks which must finish before the tmux window opens, pane commands execute immediately within the new window.

This can be used for:

• Installing dependencies: Run npm install or cargo build in a focused pane to monitor progress.
• Starting services: Launch dev servers, database containers, or file watchers automatically.
• Running agents: Initialize AI agents with specific context.

Since these run in standard tmux panes, you can interact with them (check logs, restart servers) just like a normal terminal session.

Running dependency installation (like pnpm install) in a pane command rather than post_create has a key advantage: you get immediate access to the tmux window while installation runs in the background. With post_create, you'd have to wait for the install to complete before the window even opens. This also means AI agents can start working immediately in their pane while dependencies install in parallel.

panes:
  # Pane 1: Install dependencies, then start dev server
  - command: pnpm install && pnpm run dev

  # Pane 2: AI agent
  - command: <agent>
    split: horizontal
    focus: true

Directory structure

Here's how workmux organizes your worktrees by default:

~/projects/
├── my-project/               <-- Main project directory
│   ├── src/
│   ├── package.json
│   └── .workmux.yaml
│
└── my-project__worktrees/    <-- Worktrees created by workmux
    ├── feature-A/            <-- Isolated workspace for 'feature-A' branch
    │   ├── src/
    │   └── package.json
    │
    └── bugfix-B/             <-- Isolated workspace for 'bugfix-B' branch
        ├── src/
        └── package.json

Each worktree is a separate working directory for a different branch, all sharing the same git repository. This allows you to work on multiple branches simultaneously without conflicts.

You can customize the worktree directory location using the worktree_dir configuration option (see Configuration options). The value supports ~ for the home directory and a {project} placeholder that resolves to the main worktree's directory name. This lets a single global config namespace every repo's worktrees under one root, e.g. worktree_dir: ~/.workmux/{project}.

Shell alias (recommended)

For faster typing, alias workmux to wm:

alias wm='workmux'

Commands

• add - Create a new worktree and tmux window
• merge - Merge a branch and clean up everything
• rebase - Rebase a worktree branch onto its base branch
• remove - Remove worktrees without merging
• list - List all worktrees with status
• open - Open a tmux window for an existing worktree
• close - Close a worktree's tmux window (keeps worktree)
• resurrect - Restore worktree windows after a crash
• path - Get the filesystem path of a worktree
• dashboard - Show TUI dashboard of all active agents
• sidebar - Toggle a compact agent status sidebar in tmux
• reap-agents - Exit tracked agent processes older than a threshold
• config edit - Edit the global configuration file
• init - Generate configuration file
• sandbox - Manage sandbox backends (container/Lima)
• claude prune - Clean up stale Claude Code entries
• completions - Generate shell completions
• docs - Show detailed documentation

workmux add <branch-name>

Creates a new git worktree with a matching tmux window and switches you to it immediately. If the branch doesn't exist, it will be created automatically.

• <branch-name>: Name of the branch to create or switch to, a remote branch reference (e.g., origin/feature-branch), or a GitHub fork reference (e.g., user:branch). Remote and fork references are automatically fetched and create a local branch with the derived name. Fork references derive the local branch as user-branch (e.g., someuser:feature creates local branch someuser-feature). Optional when using --pr.

Options

• --base <branch|commit|tag>: Specify a base branch, commit, or tag to branch from when creating a new branch. Overrides base_branch config. Defaults to base_branch from config, then the currently checked out branch.
• --pr <number>: Checkout a GitHub pull request by its number into a new worktree.
  • Requires the gh command-line tool to be installed and authenticated.
  • The local branch name defaults to the PR's head branch name, but can be overridden (e.g., workmux add custom-name --pr 123).
  • If that local branch already exists and has no worktree, it is reused.
• -A, --auto-name: Generate branch name from prompt using LLM. See Automatic branch name generation.
• --name <name>: Override the worktree directory and tmux window name. By default, these are derived from the branch name (slugified). Cannot be used with multi-worktree generation (--count, --foreach, or multiple --agent).
• -b, --background: Create the tmux window in the background without switching to it. Useful with --prompt-editor.
• -w, --with-changes: Move uncommitted changes from the current worktree to the new worktree, then reset the original worktree to a clean state. Useful when you've started working on main and want to move your branches to a new worktree.
• --patch: Interactively select which changes to move (requires --with-changes). Opens an interactive prompt for selecting hunks to stash.
• -u, --include-untracked: Also move untracked files (requires --with-changes). By default, only staged and modified tracked files are moved.
• -p, --prompt <text>: Provide an inline prompt that will be automatically passed to AI agent panes.
• -P, --prompt-file <path>: Provide a path to a file whose contents will be used as the prompt.
• -e, --prompt-editor: Open your $EDITOR (or $VISUAL) to write the prompt interactively.
• --prompt-file-only: Write the prompt file to the worktree without injecting it into agent commands. No agent pane is required. Useful when your editor has an embedded agent that reads .workmux/PROMPT-*.md directly.
• -l, --layout <name>: Use a named pane layout from config instead of the default panes. Cannot be combined with --agent.
• -a, --agent <name>: The agent(s) to use for the worktree(s). Can be specified multiple times to generate a worktree for each agent. Overrides the agent from your config file.
• -W, --wait: Block until the created tmux window is closed. Useful for scripting when you want to wait for an agent to complete its work. The agent can signal completion by running workmux remove --keep-branch.
• -o, --open-if-exists: If a worktree for the branch already exists, open it instead of failing. Similar to tmux new-session -A. Useful when you don't know or care whether the worktree already exists.
• -s, --session: Create a tmux session instead of a window. See Session mode for details.
• --config <path>: Use an alternate config file for this invocation. Still merges with global config.
• --fork: Fork the last conversation from the current worktree into the new one. The agent resumes with the forked conversation context. Use --fork=<session-id> to fork a specific session (prefix matching supported). Currently supports Claude Code.

Skip options

These options allow you to skip expensive setup steps when they're not needed (e.g., for documentation-only changes):

• -H, --no-hooks: Skip running post_create commands
• -F, --no-file-ops: Skip file copy/symlink operations (e.g., skip linking node_modules)
• -C, --no-pane-cmds: Skip executing pane commands (panes open with plain shells instead)

What happens

1. Determines the handle for the worktree by slugifying the branch name (e.g., feature/auth becomes feature-auth). This can be overridden with the --name flag.
2. Creates a git worktree at <worktree_dir>/<handle> (the worktree_dir is configurable and defaults to a sibling directory of your project)
3. Runs any configured file operations (copy/symlink)
4. Executes post_create commands if defined (runs before the tmux window opens, so keep them fast)
5. Creates a new tmux window named <window_prefix><handle> (e.g., wm-feature-auth with window_prefix: wm-)
6. Sets up your configured tmux pane layout
7. Automatically switches your tmux client to the new window

Examples

Basic usage

# Create a new branch and worktree
workmux add user-auth

# Use an existing branch
workmux add existing-work

# Create a new branch from a specific base
workmux add hotfix --base production

# Create a worktree from a remote branch (creates local branch "user-auth-pr")
workmux add origin/user-auth-pr

# Remote branches with slashes work too (creates local branch "feature/foo")
workmux add origin/feature/foo

# Create a worktree in the background without switching to it
workmux add feature/parallel-task --background

# Use a custom name for the worktree directory and tmux window
workmux add feature/long-descriptive-branch-name --name short

# Open existing worktree if it exists, create if it doesn't (idempotent)
workmux add my-feature -o

Checking out pull requests and fork branches

# Checkout PR #123. The local branch will be named after the PR's branch.
workmux add --pr 123

# Checkout PR #456 with a custom local branch name
workmux add fix/api-bug --pr 456

# Checkout a fork branch using GitHub's owner:branch format (copy from GitHub UI)
# Creates local branch "someuser-feature-branch" tracking the fork
workmux add someuser:feature-branch

Moving changes to a new worktree

# Move uncommitted changes to a new worktree (including untracked files)
workmux add feature/new-thing --with-changes -u

# Move only staged/modified files (not untracked files)
workmux add fix/bug --with-changes

# Interactively select which changes to move
workmux add feature/partial --with-changes --patch

AI agent prompts

# Create a worktree with an inline prompt for AI agents
workmux add feature/ai --prompt "Implement user authentication with OAuth"

# Override the default agent for a specific worktree
workmux add feature/testing -a gemini

# Create a worktree with a prompt from a file
workmux add feature/refactor --prompt-file task-description.md

# Open your editor to write a prompt interactively
workmux add feature/new-api --prompt-editor

# Write prompt file only (for editors with embedded agents like neovim)
workmux add feature/task -P task.md --prompt-file-only

Skipping setup steps

# Skip expensive setup for documentation-only changes
workmux add docs-update --no-hooks --no-file-ops --no-pane-cmds

# Skip just the file operations (e.g., you don't need node_modules)
workmux add quick-fix --no-file-ops

Scripting with --wait

# Block until the agent completes and closes the window
workmux add feature/api --wait -p "Implement the REST API, then run: workmux remove --keep-branch"

# Use in a script to run sequential agent tasks
for task in task1.md task2.md task3.md; do
  workmux add "task-$(basename $task .md)" --wait -P "$task"
done

AI agent integration

When you provide a prompt via --prompt, --prompt-file, or --prompt-editor, workmux automatically injects the prompt into panes running the configured agent command (e.g., claude, codex, opencode, gemini, kiro-cli, vibe, pi, omp, or whatever you've set via the agent config or --agent flag) without requiring any .workmux.yaml changes:

• Panes with a command matching the configured agent are automatically started with the given prompt.
• You can keep your .workmux.yaml pane configuration simple (e.g., panes: [{ command: "<agent>" }]) and let workmux handle prompt injection at runtime.

This means you can launch AI agents with task-specific prompts without modifying your project configuration for each task.

If your editor has an embedded agent (e.g., neovim with an agent plugin), use --prompt-file-only to write the prompt to .workmux/PROMPT-<branch>.md without requiring an agent pane. Your editor can then detect and consume the file on startup. This can also be set permanently in config with prompt_file_only: true.

Automatic branch name generation

The --auto-name (-A) flag generates a branch name from your prompt using an LLM. The tool used depends on your configuration:

1. auto_name.command is set: uses that command as-is
2. config.agent is a known agent (claude, gemini, codex, opencode, kiro-cli, vibe, pi, omp): uses the agent's CLI with a fast/cheap model
3. Neither: falls back to the llm CLI tool

Usage

# Opens editor for prompt, generates branch name
workmux add -A

# With inline prompt
workmux add -A -p "Add OAuth authentication"

# With prompt file
workmux add -A -P task-spec.md

Requirements

When agent is configured (e.g., agent: claude), workmux automatically uses that agent's CLI for branch naming. No additional setup is required beyond having the agent installed.

If no agent is configured and no auto_name.command is set, workmux uses the llm CLI tool:

pipx install llm

Configure a model (e.g., OpenAI):

llm keys set openai
# Or use a local model
llm install llm-ollama

If you set auto_name.command, llm is not required.

Agent profile defaults

When an agent is configured, these commands are used automatically:

To override back to llm when an agent is configured, set auto_name.command: "llm".

Configuration

Optionally configure auto-name behavior in .workmux.yaml:

auto_name:
  model: 'gemini-2.5-flash-lite'
  background: true # Always run in background when using --auto-name
  system_prompt: |
    Generate a concise git branch name based on the task description.

    Rules:
    - Use kebab-case (lowercase with hyphens)
    - Keep it short: 1-3 words, max 4 if necessary
    - Focus on the core task/feature, not implementation details
    - No prefixes like feat/, fix/, chore/

    Examples of good branch names:
    - "Add dark mode toggle" → dark-mode
    - "Fix the search results not showing" → fix-search
    - "Refactor the authentication module" → auth-refactor
    - "Add CSV export to reports" → export-csv
    - "Shell completion is broken" → shell-completion

    Output ONLY the branch name, nothing else.

To use a specific tool, set auto_name.command. The command string is split into program and arguments, and the composed prompt is piped via stdin.

auto_name:
  command: 'claude -p'

# Force llm even when an agent is configured
auto_name:
  command: 'llm'

Recommended models for fast, cheap branch name generation (with llm):

• gemini-2.5-flash-lite (recommended)
• gpt-5-nano

Parallel workflows & multi-worktree generation

workmux can generate multiple worktrees from a single add command, which is ideal for running parallel experiments or delegating tasks to multiple AI agents. This is controlled by four mutually exclusive modes:

• (-a, --agent): Create a worktree for each specified agent.
• (-n, --count): Create a specific number of worktrees.
• (--foreach): Create worktrees based on a matrix of variables.
• stdin: Pipe input lines to create worktrees with templated prompts.

When using any of these modes, branch names are generated from a template, and prompts are templated with variables. Single-worktree prompts are passed through literally, so common syntax like GitHub Actions ${{ ... }} does not need to be escaped.

Multi-worktree options

• -a, --agent <name>: When used multiple times, creates one worktree for each agent.
• -n, --count <number>: Creates <number> worktree instances. Can be combined with a single --agent flag to apply that agent to all instances.
• --foreach <matrix>: Creates worktrees from a variable matrix string. The format is "var1:valA,valB;var2:valX,valY". All value lists must have the same length. Values are paired by index position (zip, not Cartesian product): the first value of each variable goes together, the second with the second, etc.
• --branch-template <template>: A MiniJinja (Jinja2-compatible) template for generating branch names.
  • Available variables: {{ base_name }}, {{ agent }}, {{ num }}, {{ index }}, {{ input }} (stdin), and any variables from --foreach.
  • Default: {{ base_name }}{% if agent %}-{{ agent | slugify }}{% endif %}{% for key, value in foreach_vars %}-{{ value | slugify }}{% endfor %}{% if num %}-{{ num }}{% endif %}
• --max-concurrent <number>: Limits how many worktrees run simultaneously. When set, workmux creates up to <number> worktrees, then waits for any window to close before starting the next. Requires agents to close windows when done (e.g., via prompt instruction to run workmux remove --keep-branch).

Prompt templating

When generating multiple worktrees, any prompt provided via -p, -P, or -e is treated as a MiniJinja template. You can use variables from your generation mode to create unique prompts for each agent or instance. For ordinary single-worktree add commands, prompt text is not templated.

Variable matrices in prompt files

Instead of passing --foreach on the command line, you can specify the variable matrix directly in your prompt file using YAML frontmatter. This is more convenient for complex matrices and keeps the variables close to the prompt that uses them.

Format:

Create a prompt file with YAML frontmatter at the top, separated by ---:

Example 1: mobile-task.md

---
foreach:
  platform: [iOS, Android]
  lang: [swift, kotlin]
---

Build a {{ platform }} app using {{ lang }}. Implement user authentication and
data persistence.

workmux add mobile-app --prompt-file mobile-task.md
# Generates worktrees: mobile-app-ios-swift, mobile-app-android-kotlin

Example 2: agent-task.md (using agent as a foreach variable)

---
foreach:
  agent: [claude, gemini]
---

Implement the dashboard refactor using your preferred approach.

workmux add refactor --prompt-file agent-task.md
# Generates worktrees: refactor-claude, refactor-gemini

Behavior:

• Variables from the frontmatter are available in both the prompt template and the branch name template
• All value lists must have the same length, and values are paired by index position (same zip behavior as --foreach)
• CLI --foreach overrides frontmatter with a warning if both are present
• Works with both --prompt-file and --prompt-editor

Stdin input

You can pipe input lines to workmux add to create multiple worktrees. Each line becomes available as the {{ input }} template variable in your prompt. This is useful for batch-processing tasks from external sources.

Plain text: Each line becomes {{ input }}

echo -e "api\nauth\ndatabase" | workmux add refactor -P task.md
# {{ input }} = "api", "auth", "database"

JSON lines: Each key becomes a template variable

gh repo list --json url,name --jq -c '.[]' | workmux add analyze \
  --branch-template '{{ base_name }}-{{ name }}' \
  -P prompt.md
# Line: {"url":"https://github.com/raine/workmux","name":"workmux"}
# Variables: {{ url }}, {{ name }}, {{ input }} (raw JSON line)

This lets you structure data upstream with jq and use meaningful branch names while keeping the full URL available in your prompt.

Behavior:

• Empty lines and whitespace-only lines are filtered out
• Stdin input cannot be combined with --foreach (mutually exclusive)
• JSON objects (lines starting with {) are parsed and each key becomes a variable
• {{ input }} always contains the raw line
• If JSON contains an input key, it overwrites the raw line value

Examples

# Create one worktree for claude and one for gemini with a focused prompt
workmux add my-feature -a claude -a gemini -p "Implement the new search API integration"
# Generates worktrees: my-feature-claude, my-feature-gemini

# Create 2 instances of the default agent
workmux add my-feature -n 2 -p "Implement task #{{ num }} in TASKS.md"
# Generates worktrees: my-feature-1, my-feature-2

# Create worktrees from a variable matrix
workmux add my-feature --foreach "platform:iOS,Android" -p "Build for {{ platform }}"
# Generates worktrees: my-feature-ios, my-feature-android

# Create agent-specific worktrees via --foreach
workmux add my-feature --foreach "agent:claude,gemini" -p "Implement the dashboard refactor"
# Generates worktrees: my-feature-claude, my-feature-gemini

# Use frontmatter in a prompt file for cleaner syntax
# task.md contains:
# ---
# foreach:
#   env: [staging, production]
#   task: [smoke-tests, integration-tests]
# ---
# Run {{ task }} against the {{ env }} environment
workmux add testing --prompt-file task.md
# Generates worktrees: testing-staging-smoke-tests, testing-production-integration-tests

# Pipe input from stdin to create worktrees
# review.md contains: Review the {{ input }} module for security issues.
echo -e "auth\npayments\napi" | workmux add review -A -P review.md
# Generates worktrees with LLM-generated branch names for each module

Recipe: Batch processing with worker pools

Combine stdin input, prompt templating, and concurrency limits to create a worker pool that processes items from an external command.

Example: Generate test scaffolding for untested files

# generate-tests.md contains:
# Read the file at {{ input }} and generate a test suite covering
# the exported functions. Focus on happy path and edge cases.
# When done, run: workmux remove --keep-branch

find src/utils -name "*.ts" ! -name "*.test.ts" | \
  workmux add add-tests \
    --branch-template '{{ base_name }}-{{ index }}' \
    --prompt-file generate-tests.md \
    --max-concurrent 3 \
    --background

• find ... lists files without tests (one per line) piped to stdin
• --branch-template uses {{ index }} for unique branch names
• --prompt-file uses {{ input }} to pass each file path to the agent
• --max-concurrent 3 limits parallel agents to avoid rate limits
• --background runs without switching focus

workmux merge [branch-name]

Merges a branch into a target branch (main by default) and automatically cleans up all associated resources (worktree, tmux window, and local branch).

[!TIP] merge vs remove: Use merge when you want to merge directly without a pull request. If your workflow uses pull requests, use remove to clean up after your PR is merged on the remote.

• [branch-name]: Optional name of the branch to merge. If omitted, automatically detects the current branch from the worktree you're in.

Options

• --into <branch>: Merge into the specified branch instead of the main branch. Useful for stacked PRs, git-flow workflows, or merging subtasks into a parent feature branch. If the target branch has its own worktree, the merge happens there; otherwise, the main worktree is used.
• --ignore-uncommitted: Commit any staged changes before merging without opening an editor
• --keep, -k: Keep the worktree, window, and branch after merging (skip cleanup). Useful when you want to verify the merge before cleaning up.
• --cleanup: Clean up after merging, overriding merge_keep: true.
• --notification: Show a system notification on successful merge. Useful when delegating merge to an AI agent and you want to be notified when it completes.

Merge strategies

By default, workmux merge performs a standard merge commit (configurable via merge_strategy). You can override the configured behavior with these mutually exclusive flags:

• --rebase: Rebase the feature branch onto the target before merging (creates a linear history via fast-forward merge). If conflicts occur, you'll need to resolve them manually in the worktree and run git rebase --continue.
• --squash: Squash all commits from the feature branch into a single commit on the target. You'll be prompted to provide a commit message in your editor.

If you don't want to have merge commits in your main branch, use the rebase merge strategy, which does --rebase by default.

# ~/.config/workmux/config.yaml
merge_strategy: rebase

To keep the worktree, window, and branch after every merge unless overridden, set:

merge_keep: true

Use workmux merge --cleanup to clean up for a single merge when this default is enabled.

What happens

1. Determines which branch to merge (specified branch or current branch if omitted)
2. Determines the target branch (--into or main branch from config)
3. Checks for uncommitted changes (errors if found, unless --ignore-uncommitted is used)
4. Commits staged changes if present (unless --ignore-uncommitted is used)
5. Merges your branch into the target using the selected strategy (default: merge commit)
6. Deletes the tmux window unless keep behavior is enabled via --keep or merge_keep: true
7. Removes the worktree unless keep behavior is enabled via --keep or merge_keep: true
8. Deletes the local branch unless keep behavior is enabled via --keep or merge_keep: true

Typical workflow

When you're done working in a worktree, simply run workmux merge from within that worktree's tmux window. The command will automatically detect which branch you're on, merge it into main, and close the current window as part of cleanup.

Examples

# Merge branch into main (default: merge commit)
workmux merge user-auth

# Merge the current worktree you're in
# (run this from within the worktree's tmux window)
workmux merge

# Rebase onto main before merging for a linear history
workmux merge user-auth --rebase

# Squash all commits into a single commit
workmux merge user-auth --squash

# Merge but keep the worktree/window/branch to verify before cleanup
workmux merge user-auth --keep
# ... verify the merge in main ...
workmux remove user-auth  # clean up later when ready

# Merge into a different branch (stacked PRs)
workmux merge feature/subtask --into feature/parent

workmux rebase [name]

Rebases a worktree branch onto its saved base branch. If the branch does not have a saved local base branch, workmux rebases onto the configured main branch.

• [name]: Optional worktree name or branch. If omitted, workmux detects the current worktree from the current directory.

What happens

1. Determines which worktree branch to rebase
2. Reads the saved base branch recorded when the worktree was created
3. Falls back to the configured main branch when the saved base is not a local branch
4. Runs git rebase <base> inside the worktree
5. Leaves the worktree, window, and branch in place

Examples

workmux rebase user-auth
workmux rebase

workmux remove [name]... (alias: rm)

Removes worktrees, tmux windows, and branches without merging (unless you keep the branches). Useful for abandoning work or cleaning up experimental branches. Supports removing multiple worktrees in a single command.

• [name]...: One or more worktree names (the directory names). Defaults to current directory name if omitted.

Options

• --all: Remove all worktrees at once (except the main worktree). Prompts for confirmation unless --force is used. Safely skips worktrees with uncommitted changes or unmerged commits.
• --gone: Remove worktrees whose upstream remote branch has been deleted (e.g., after a PR is merged on GitHub). Automatically runs git fetch --prune first.
• --force, -f: Skip confirmation prompt and ignore uncommitted changes
• --keep-branch, -k: Remove only the worktree and tmux window while keeping the local branch

Examples

# Remove the current worktree (run from within the worktree)
workmux remove

# Remove a specific worktree with confirmation if unmerged
workmux remove experiment

# Remove multiple worktrees at once
workmux rm feature-a feature-b feature-c

# Remove multiple worktrees with force (no confirmation)
workmux rm -f old-work stale-branch

# Use the alias
workmux rm old-work

# Remove worktree/window but keep the branch
workmux remove --keep-branch experiment

# Force remove without prompts
workmux rm -f experiment

# Remove worktrees whose remote branches were deleted (e.g., after PR merge)
workmux rm --gone

# Force remove all gone worktrees (no confirmation)
workmux rm --gone -f

# Remove all worktrees at once
workmux rm --all

workmux rename [old-name] <new-name>

Renames a worktree's directory, its tmux window or session, and the per-worktree workmux metadata. Optionally also renames the underlying git branch.

• [old-name]: Optional current worktree name. Defaults to the current worktree when run from inside one.
• <new-name>: The new handle (directory name and tmux window/session base name).

Options

• --branch, -b: Also rename the underlying git branch to match <new-name>. Fails if the worktree is on a detached HEAD.

Examples

# Rename a worktree from inside it
workmux rename feature-new

# Rename a specific worktree by name
workmux rename feature-old feature-new

# Also rename the branch to match
workmux rename feature-old feature-new --branch

Rename is non-destructive: uncommitted changes and untracked files are preserved. The main worktree cannot be renamed. Collisions (existing target path, existing tmux target, or existing branch) are rejected before any changes are made.

workmux list (alias: ls)

Lists all git worktrees with their agent status, multiplexer window status, and merge status. Supports filtering by worktree handle or branch name.

Arguments

• [worktree-or-branch...]: Filter by worktree handle (directory name) or branch name. Accepts multiple values. When omitted, shows all worktrees.

Options

• --pr: Show GitHub PR status for each worktree. Requires the gh CLI to be installed and authenticated. Note that it shows pull requests' statuses with Nerd Font icons, which requires Nerd Font compatible font installed.
• --json: Output as JSON. Produces a JSON array of objects with fields: handle, branch, path, is_main, mode, has_uncommitted_changes, is_open, created_at.

Examples

# List all worktrees
workmux list

# List with PR status
workmux list --pr

# Output as JSON for scripting
workmux list --json

# Filter to specific worktrees
workmux list my-feature
workmux list feature-auth feature-api

Example output

BRANCH      AGE  AGENT  MUX  UNMERGED  PATH
main        -    -      -    -         ~/project
user-auth   2h   🤖     ✓    -         ~/project__worktrees/user-auth
bug-fix     3d   ✅     ✓    ●         ~/project__worktrees/bug-fix
api-work    1w   -      ✓    -         ~/project__worktrees/api-work

Key

• AGE shows how old the worktree is (e.g., 2h, 3d, 1w, 2mo)
• AGENT shows the current agent status (see status tracking):
  • 🤖 = working, 💬 = waiting for input, ✅ = finished
  • Multiple agents per worktree show a count (e.g., 2🤖 1✅)
• ✓ in MUX column = multiplexer window exists for this worktree
• ● in UNMERGED column = branch has commits not merged into main
• - = not applicable

workmux config edit

…view the full README on GitHub.