raine 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 viawindow_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:
-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 handle name-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
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 send myproject:docs "update the API section" # cross-project
# Run shell commands in an agent's worktree
workmux run agent-a -- pytest tests/ # wait and stream output
workmux run agent-a -b -- npm run build # run in background
Other commands
workmux path <name> # print worktree filesystem path
workmux dashboard # TUI dashboard of all active agents
workmux config edit # open global config in $EDITOR
workmux config reference # print default config with all options documented
workmux init # generate .workmux.yaml in current project
Configuration
Two levels: global (~/.config/workmux/config.yaml) and project
(.workmux.yaml). Project overrides global.
Key options
agent: claude # default agent for <agent> placeholder
merge_strategy: rebase # merge, rebase, or squash
mode: window # window or session
panes:
- command: <agent> # <agent> resolves to configured agent
focus: true
- split: horizontal # second pane with shell
files:
copy:
- .env # copy from main worktree
symlink:
- node_modules # symlink from main worktree
post_create:
- '<global>' # include global hooks
- npm install # project-specific setup
base_branch: develop # default base for new worktrees
window_prefix: wm- # tmux window name prefix
Use '<global>' in project config arrays to include global values.
For the full configuration reference with all options documented, run
workmux config reference.
Agent detection
Built-in agents (claude, gemini, codex, opencode, kiro-cli,
vibe) are auto-detected in pane commands and receive prompt injection
automatically. The <agent> placeholder resolves to the configured agent.
Common Workflows
Finishing work: direct merge
Use /merge to commit, rebase onto the base branch, and merge in one
step. This cleans up the worktree, tmux window, and branch.
Finishing work: PR-based
- Commit changes
git push -u origin HEAD- Use
/open-prto write a PR description and open in browser - After PR is merged remotely, clean up with
workmux rm --gone
Delegating tasks
Use /worktree to spin off tasks into parallel worktree agents. The
agent writes a prompt file and runs workmux add -b -P <file>.
For full lifecycle orchestration (spawn, monitor, merge), use
/coordinator.
Cross-project worktree creation
workmux add creates worktrees in the current git repo and adds the
window to the current tmux session. To create a worktree in a different
project, run workmux add inside that project's tmux session.
Discover project paths from existing sessions:
tmux list-sessions -F '#{session_name} #{session_path}'
Then create the worktree in the target session:
# If the session exists:
tmux new-window -t <session> -c <project-path> \
"workmux add <branch> -b -P <prompt-file>; exit"
# If the session does not exist, create it first:
tmux new-session -d -s <session> -c <project-path> && \
tmux new-window -t <session> -c <project-path> \
"workmux add <branch> -b -P <prompt-file>; exit"
The temporary window closes when workmux add finishes; the worktree
window that workmux creates stays in the session.
Do NOT research before dispatching. Use context you already have, but do not explore or read code just to write the prompt. Worktree agents can read files from other projects via absolute paths, so reference other projects by path and let the agent explore on its own.
Related Skills
/merge: commit, rebase, and merge the current branch/rebase: rebase with smart conflict resolution/worktree: delegate tasks to parallel worktree agents/coordinator: orchestrate multiple agents (spawn, monitor, merge)/open-pr: write PR description and open in browser