raine/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] I'm building aven, a local-first task manager for power users and agents who live in the terminal.

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 (requires rustup):

cargo install workmux

mise:

mise use -g cargo:raine/workmux

Nix (flake and home-manager setup):

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

   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:

   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 show