/workmux

name: workmux
description: Reference for the workmux CLI that manages git worktrees and
  tmux windows as isolated development environments. Use when the user
  mentions workmux, worktrees, or parallel agent workflows.
disable-model-invocation: true

workmux

workmux manages git worktrees paired with tmux windows for parallel development. Each worktree is an isolated workspace with its own branch, terminal state, and AI agent.

**If the user asks you to create worktrees or dispatch tasks (e.g., "/workmux add ..."), you are a dispatcher.** Write prompt files and run commands. Do NOT explore, read, or research the codebase first. Use context you already have. The worktree agent does all the work.

Key Concepts

• **Handle**: the worktree directory name, derived from the branch name

(slugified). Used to identify worktrees in all commands

• **Worktree directory**: defaults to `<project>__worktrees/<handle>` as a

sibling of the project root

• **Window prefix**: tmux windows are named `wm-<handle>` by default

(configurable via `window_prefix`)

• **Agent status**: agents report status via hooks: working, waiting (needs

input), done (finished)

Commands

Create a worktree

workmux add <branch-name>

Creates a git worktree, runs file operations and hooks, creates a tmux window with configured pane layout, and switches to it.

Key flags:

• `--pr <number|url>`: checkout a GitHub pull request by number or full URL into

a new worktree. The local branch defaults to the PR head branch name. Pass `<branch-name>` to override it, for example `workmux add --pr https://github.com/owner/repo/pull/123 custom-name`. Requires authenticated `gh`.

• `-b, --background`: create without switching to it
• `-p <text>`: inline prompt for AI agent panes
• `-P <file>`: prompt from file
• `-e, --prompt-editor`: write prompt in $EDITOR
• `-A, --auto-name`: generate branch name from prompt via LLM
• `-a <agent>`: override the agent (can specify multiple for multi-worktree)
• `-w, --with-changes`: move uncommitted changes to the new worktree
• `--base <branch>`: branch from a specific base
• `--name <name>`: override the worktree handle
• `--target-name <name>`: override the workmux-managed tmux window or session name
• `--parent-session <session>`: put a window-mode target in this tmux session,

creating the parent session when it does not exist

• `-o, --open-if-exists`: open existing worktree if it exists (idempotent)
• `-W, --wait`: block until the tmux window is closed
• `-n, --count <N>`: create N worktree instances
• `--foreach <matrix>`: create worktrees from variable matrix
• `--no-hooks, --no-file-ops, --no-pane-cmds`: skip setup steps

Create without a multiplexer

workmux add <branch-name> --headless --json

Runs file operations and post-create hooks without creating a window or starting an agent. No running multiplexer is required. `--json` requires `--headless` and returns one JSON receipt with the handle, worktree path, and effective working directory; hook output goes to stderr.

Use an explicit local branch name. Supports `--base`, `--name`, `--no-hooks`, and `--no-file-ops`, but not PR checkout, prompts, `--background`, or other mux/agent options. Worktrees persist until removed: clean up with `workmux remove <handle>` or attach a window later with `workmux open <handle>`.

List worktrees

workmux list          # all worktrees
workmux list --pr     # with GitHub PR status
workmux list <name>   # filter by handle or branch

Shows branch, agent status, tmux window status, and unmerged commits.

Merge a branch

workmux merge                 # merge current branch into main
workmux merge <branch>        # merge specific branch
workmux merge --rebase        # rebase before merging (linear history)
workmux merge --squash        # squash all commits into one
workmux merge --into <branch> # merge into a different target branch
workmux merge --keep          # merge but keep worktree/window/branch
workmux merge --notification  # show system notification on success

Merges the branch, deletes the tmux window, removes the worktree, and deletes the local branch. Use the `/merge` skill for the full workflow (commit, rebase, then merge).

Remove worktrees

workmux remove                # current worktree
workmux remove <name>...      # specific worktrees
workmux rm --gone             # worktrees whose remote branch was deleted
workmux rm --all              # all worktrees
workmux rm -f <name>          # force, skip confirmation
workmux rm --keep-branch      # keep the branch, remove worktree + window

Open / close windows

workmux open <name>           # open or switch to tmux window
workmux open --new            # force a new window (creates suffix -2, -3)
workmux open <name> -p "..."  # open with a prompt for agent panes
workmux close <name>          # close tmux window, keep worktree

Interact with other agents

These commands target agents by their worktree handle. If the handle is not found in the current repo, workmux searches all active agents globally. Use `project:handle` syntax to disambiguate when names collide.

# Check agent statuses
workmux status                          # all agents
workmux status auth api-tests           # specific agents

# Wait for agents
workmux wait agent-a agent-b            # block until done
workmux wait agent-a --timeout 3600     # with timeout (seconds)
workmux wait agent-a agent-b --any      # wait for first to finish
workmux wait agent-a --status working   # wait for specific status

# Read agent terminal output
workmux capture agent-a                 # last 200 lines (default)
workmux capture agent-a -n 50           # last 50 lines

# Send instructions to an agent
workmux send agent-a "fix the tests"    # short message
workmux send agent-a "/merge"           # send a skill command
workmux send agent-a -f followup.md     # from file
workmux