workmux icon

Parallel development in tmux* with git worktrees

πŸ“– Documentation Β· Install Β· Quick start Β· Commands Β· Changelog

--- Giga opinionated zero-friction workflow tool for managing [git worktrees](https://git-scm.com/docs/git-worktree) 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](https://raine.dev/blog/introduction-to-workmux/) for a quick overview. ![workmux screenshot](https://raw.githubusercontent.com/raine/workmux/refs/heads/main/meta/screenshot_20260329_165534.webp) aven: one task queue for you and your coding agents Also from the author of workmux: aven, one queue for every project, with a keyboard-driven TUI for you and a CLI for your agents. ## 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?](#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](#workmux-dashboard) for monitoring agents, reviewing changes, and sending commands - [Sidebar](https://workmux.dev/guide/sidebar/) for a persistent, at-a-glance view of all agents across tmux windows or Zellij tabs - [Delegate tasks to worktree agents](#delegating-tasks-with-worktree) with the `/worktree` skill - [Display agent status in tmux window names](#agent-status-tracking) - 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](#sandbox) in containers or VMs for enhanced security - [Run agents on a remote server](https://workmux.dev/guide/remote/) over SSH while others stay local - [Automatic branch name generation](#automatic-branch-name-generation) from prompts using LLM - Shell completions ## What people say - *"I've been using (and loving) workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow."* - [Coolin96 on Hacker News](https://news.ycombinator.com/item?id=46029809) - *"Thank you so much for your work with workmux! It's a tool I've been wanting to exist for a long time."* - [rstacruz on GitHub](https://github.com/raine/workmux/issues/2) - *"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 on GitHub](https://github.com/raine/workmux/issues/33) - *"I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows."* - [dedbrizz on Threads](https://www.threads.com/@dedbrizz/post/DVt1DtLkr_l) - *"Since I discovered workmux I'm cooking. Amazing parallel-agent driver if you like tmux and want to keep your config."* - [MatijaSosic on X](https://x.com/MatijaSosic/status/2080022087281127659) - *"Using workmux with a well-configured tmux has been a breath of fresh air"* - [sbeirakh_il on X](https://x.com/sbeirakh_il/status/2080279929778733305) - *"I've been using it for about a month now, and it's been nothing but great."* - [gabrielrockson_ on X](https://x.com/gabrielrockson_/status/2080386326566736189) - *"I still don't see the need for Herdr. Workmux adds busy/question/done status, manages worktrees by itself, and etc. It lives on an already existing tmux setup."* - [13hcoks on X](https://x.com/13hcoks/status/2080278051309355485) - *"workmux is fantastic. nothing too fancy, solves a real problem and stays in TMUX ❀️"* - [devopstoolbox on X](https://x.com/devopstoolbox/status/2094442083717390547) - *"Workmux is fantastic if you're mostly terminal bound."* - [cody1786 on X](https://x.com/cody1786/status/2033959173361213870) - *"Want modern terminal workspace features without abandoning your setup? Here is how to keep Tmux and boost your workflow using Workmux."* - [Sam Natale on YouTube](https://www.youtube.com/watch?v=ww1wykxJps8) ## Community videos Some kind people have made videos about workmux on YouTube. If you're looking for a demo, check them out.
Tmux is Still Better Than Herdr (Here's Why)
Tmux is Still Better Than Herdr (Here's Why)
Sam Natale
I Don't Want a New Terminal. I Want THIS for Tmux.
I Don't Want a New Terminal. I Want THIS for Tmux.
DevOps Toolbox
Tmux Didn't Need a Replacement, It Needed Workmux
Tmux Didn't Need a Replacement, It Needed Workmux
Seth Phaeno
## Installation **Official sources:** [github.com/raine/workmux](https://github.com/raine/workmux) and [workmux.dev](https://workmux.dev/). This project is not affiliated with workmux.com. ### Bash YOLO ```bash curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash ``` ### Homebrew (macOS/Linux) ```bash brew install raine/workmux/workmux ```
Other methods (Cargo, mise, Nix) **Cargo** (requires [rustup](https://rustup.rs/)): ```bash cargo install workmux ``` **mise:** ```bash mise use -g cargo:raine/workmux ``` **Nix** ([flake and home-manager setup](https://workmux.dev/guide/nix)): ```bash nix profile install github:raine/workmux ```
--- For manual installation, see [pre-built binaries](https://github.com/raine/workmux/releases/latest). ## Quick start > [!NOTE] > workmux requires a terminal multiplexer. Make sure you have > [tmux](https://github.com/tmux/tmux) (or > [WezTerm](https://raine.github.io/workmux/guide/wezterm) / > [Kitty](https://raine.github.io/workmux/guide/kitty) / > [Zellij](https://raine.github.io/workmux/guide/zellij)) installed and running > before you start. See [My tmux setup](https://raine.dev/blog/my-tmux-setup/) > if you need a starting point. 1. **Initialize configuration (optional)**: ```bash 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**: ```bash workmux add new-feature ``` This will: - Create a git worktree at `/../__worktrees/new-feature` - Copy config files and symlink dependencies (if [configured](#file-operations)) - Run any [`post_create`](#lifecycle-hooks) 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](https://workmux.dev/guide/monorepos#nested-configuration) for details. For hook lists (`post_create`, `pre_merge`, `pre_remove`) and file operation lists (`files.copy`, `files.symlink`), you can use `""` 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`: ```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 confirm_unmerged_removal: false # Remove unmerged branches without confirmation agent: claude panes: - command: # Start the configured agent (e.g., claude) focus: true - split: horizontal # Second pane with default shell ``` ### Project configuration example `.workmux.yaml`: ```yaml post_create: - '' - mise use files: symlink: - '' # Include global symlinks (node_modules) - .pnpm-store # Add project-specific symlink panes: - command: pnpm install focus: true - command: split: horizontal - command: pnpm run dev split: vertical ``` For a real-world example, see [workmux's own `.workmux.yaml`](https://github.com/raine/workmux/blob/main/.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 ref for new worktrees, or `auto` for the effective main branch | Current branch | | `worktree_dir` | Directory for worktrees (absolute or relative). Supports `~` and `{project}`. | `__worktrees/` | | `window_prefix` | Prefix for tmux window/session names. Supports `{project}`. | `wm-` | | `mode` | Tmux mode (`window` or `session`) | `window` | | `default_session` | Session to return to when a workmux session closes (session mode) | Previous session | | `window_placement` | New tmux window placement (`after_current` or `rightmost`) | `after_current` | | `agent` | Default agent for `` placeholder | `claude` | | `agents` | Named agent commands ([docs](https://workmux.dev/guide/agents#named-agents), global-only) | `{}` | | `merge_strategy` | Default merge strategy (`merge`, `rebase`, `squash`) | `merge` | | `merge_keep` | Keep resources after `workmux merge` by default | `false` | | `confirm_unmerged_removal` | Confirm before deleting branches with commits not merged into their base | `true` | | `theme` | Dashboard color scheme ([custom colors](https://workmux.dev/guide/configuration#custom-colors)) | `default` (auto dark/light) | Set `base_branch: auto` to create independent work streams from each repository's effective main branch. Workmux uses configured `main_branch`, then the local `origin/HEAD`, `main`, or `master`. Detection uses local Git state and does not fetch. Omitting `base_branch` continues to create branches from the checked-out branch. #### 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 multiplexer pane layout with the `panes` array. For multiple windows in session mode, use [`windows`](#multiple-windows-per-session) instead (they are mutually exclusive). ```yaml panes: - command: name: agent focus: true - command: npm run dev name: dev split: horizontal size: 15 ``` Each pane supports: | Option | Description | Default | | ------------ | ---------------------------------------------------------------------------- | ---------------- | | `name` | Pane display name (currently applied by the Zellij backend) | --- | | `command` | Command to run (see [agent placeholders](#agent-placeholders)) | Shell | | `focus` | Whether this pane receives focus | `false` | | `zoom` | Zoom pane to fullscreen (implies `focus: true`) | `false` | | `split` | Split direction (`horizontal` or `vertical`) | --- | | `size` | Absolute size in lines/cells | 50% | | `percentage` | Size as percentage (1-100) | 50% | | `target` | 0-based pane index to split from; defaults to most recent pane | most recent pane | Use `target` when you want to split something other than the pane that was just created. The target must reference an earlier pane in the same layout. ```yaml panes: - command: nvim focus: true - command: pnpm install && pnpm run dev split: vertical size: 15 - command: split: horizontal target: 0 ``` This creates three panes: `nvim` is at the top left, the agent is to its right, and the dev server spans the bottom. ##### Agent placeholders - ``: resolves to the configured agent (from `agent` config or `--agent` flag) Built-in agents (`claude`, `gemini`, `agy`, `codex`, `copilot`, `opencode`, `kiro-cli`, `vibe`, `pi`, `omp`, `grok`) are auto-detected when used as literal commands and receive prompt injection automatically, without needing the `` placeholder or a matching `agent` config: ```yaml 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. Antigravity CLI support covers command detection, prompt injection, and status tracking via lifecycle hooks installed by `workmux setup`. #### Named layouts Define reusable pane arrangements in the `layouts` map and select one at add-time with `-l/--layout`: ```yaml layouts: design: panes: - command: focus: true - command: split: vertical review: panes: - command: ``` ```bash 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: ```yaml 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](https://workmux.dev/guide/monorepos#nested-configuration)) and receive environment variables: `WM_HANDLE`, `WM_WORKTREE_PATH`, `WM_PROJECT_ROOT`, `WM_CONFIG_DIR`. `hook_shell` is an argv list containing the executable followed by its arguments. Workmux appends each hook command as the final argument. It defaults to `["bash", "-c"]` for compatibility. Machine-specific paths belong in global configuration: ```yaml hook_shell: ["/opt/homebrew/bin/bash", "-c"] ``` A project can override the complete argv, or inherit the global value by omitting `hook_shell`. The argv must contain a non-empty executable. Shell flags and error handling apply only when included explicitly. `WM_PROJECT_ROOT` points to the repository's main worktree, regardless of where the selected config is stored. `WM_CONFIG_DIR` points to the corresponding config directory in the new worktree, which may differ from `WM_WORKTREE_PATH` when using nested configs. | Hook | When it runs | Additional env vars | | ------------- | ------------------------------------------------- | ------------------------------------ | | `post_create` | After worktree creation, before tmux window opens | β€” | | `pre_merge` | Before merging (aborts on failure) | `WM_BRANCH_NAME`, `WM_TARGET_BRANCH` | | `pre_remove` | Before worktree removal (aborts on failure) | β€” | Example: ```yaml post_create: - direnv allow pre_merge: - just check ``` In Node.js projects, `pre_remove` defaults to a fast `node_modules` cleanup, and defining your own commands replaces that default. Use `""` to keep it: ```yaml pre_remove: - cp -r test-results/ "$WM_PROJECT_ROOT/artifacts/$WM_HANDLE/" - "" ``` #### Agent status icons Customize the icons shown in tmux window names: ```yaml 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 `__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. ```yaml panes: # Pane 1: Install dependencies, then start dev server - command: pnpm install && pnpm run dev # Pane 2: AI agent - command: 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](#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`: ```bash alias wm='workmux' ``` ## Commands - [`add`](#workmux-add-branch-name) - Create a new worktree and tmux window - [`merge`](#workmux-merge-branch-name) - Merge a branch and clean up everything - [`rebase`](#workmux-rebase-name) - Rebase a worktree branch onto its base branch - [`remove`](#workmux-remove-name-alias-rm) - Remove worktrees without merging - [`list`](#workmux-list) - List all worktrees with status - [`open`](#workmux-open-name) - Open a tmux window for an existing worktree - [`close`](#workmux-close-name) - Close a worktree's tmux window (keeps worktree) - [`resurrect`](#workmux-resurrect) - Restore worktree windows after a crash - [`path`](#workmux-path-name) - Get the filesystem path of a worktree - [`dashboard`](#workmux-dashboard) - Show TUI dashboard of all active agents - [`sidebar`](#workmux-sidebar) - Toggle a compact agent status sidebar in tmux, Zellij or Rex - [`reap-agents`](#workmux-reap-agents) - Exit tracked agent processes older than a threshold - [`config edit`](#workmux-config-edit) - Edit the global configuration file - [`init`](#workmux-init) - Generate configuration file - [`sandbox`](#workmux-sandbox) - Manage sandbox backends (container/Lima) - [`claude prune`](#workmux-claude-prune) - Clean up stale Claude Code entries - [`completions`](#workmux-completions-shell) - Generate shell completions - [`docs`](#workmux-docs) - Show detailed documentation ### `workmux add ` 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. - ``: 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 `: Specify a base branch, commit, or tag to branch from when creating a new branch. Overrides `base_branch` config. The config value `auto` uses the effective main branch. Without either setting, workmux uses the currently checked out branch. - `--pr `: Checkout a GitHub pull request by its number or full URL into a new worktree. - Requires the `gh` command-line tool to be installed and authenticated. - URLs use the form `https://github.com///pull/`. - 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](#automatic-branch-name-generation). - `--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`. - `--remote []`: Create the workspace on a [remote server](https://workmux.dev/guide/remote/). The name is optional when `placement` names a remote or only one is configured. Put the branch name first: `workmux add my-branch --remote`. - `--local`: Create the workspace locally even when `placement` names a remote. - `-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 `: Provide an inline prompt that will be automatically passed to AI agent panes. - `-P, --prompt-file `: 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 `: Use a named pane layout from config instead of the default panes. Cannot be combined with `--agent`. - `-a, --agent `: 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](#session-mode) for details. - `--dry-run`: Print the resolved worktree path, branch, base, multiplexer target, file operations, and post-create hooks without creating or modifying anything. - `--headless`: Create the worktree, apply file operations, and run `post_create` hooks without requiring or creating a multiplexer target. - `--json`: Emit a versioned provisioning receipt on stdout. Requires `--headless`. Hook output and diagnostics use stderr. - `--config `: 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=` to fork a specific session (prefix matching supported). Supports Claude Code and Codex. #### 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 `/` (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 `` (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 In tmux window mode without `--parent-session`, `$TMUX_PANE` identifies the calling pane and its parent session. When `$TMUX_PANE` is absent or stale, workmux uses live pane working directories when their closest matches identify one session. A tmux server with one session is the final fallback. Remaining ambiguity requires `--parent-session `. The working directory selects the Git repository and only provides conservative evidence for tmux placement. #### Headless provisioning Automation can provision a fully configured worktree without asking workmux to manage its terminal process: ```bash workmux add suba-parser-a1b2c3d4 \ --name suba-parser-a1b2c3d4 \ --headless \ --json ``` The command creates or checks out the local branch, applies configured file operations, and runs `post_create` hooks. It does not inspect or create mux sessions, windows, panes, layouts, or pane commands. The JSON receipt includes `schema_version`, `handle`, `branch`, absolute `worktree_path`, absolute `working_directory`, `base_branch`, and `post_create_hooks_run`. Headless worktrees persist until removed with `workmux remove `. A later `workmux open ` attaches a workmux-managed multiplexer target. Headless branch arguments are local branch names; remote branch syntax is rejected. Prompt, rescue, multi-worktree, sandbox, wait, dry-run, and mux-specific options are not accepted with `--headless`. #### Examples ##### Basic usage ```bash # 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 # Preview the resolved plan without creating anything workmux add feature/parallel-task --dry-run # 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 ```bash # Checkout PR #123. The local branch will be named after the PR's branch. workmux add --pr 123 # Checkout a pull request from its full GitHub URL with a custom local branch workmux add --pr https://github.com/raine/workmux/pull/456 fix/api-bug # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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`, `copilot`, `opencode`, `gemini`, `agy`, `kiro-cli`, `vibe`, `pi`, `omp`, `grok`, 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: "" }]`) 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-.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`, `agy`, `codex`, `opencode`, `kiro-cli`, `vibe`, `pi`, `omp`): uses the agent's CLI with a fast/cheap model 3. Neither: falls back to the [`llm`](https://llm.datasette.io/) CLI tool ##### Usage ```bash # 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: ```bash pipx install llm ``` Configure a model (e.g., OpenAI): ```bash 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: | Agent | Auto-name command | | ---------- | ---------------------------------------------------------------------------- | | `claude` | `claude --model haiku --no-session-persistence -p` | | `gemini` | `gemini -m gemini-2.5-flash-lite -p` | | `codex` | `codex exec --ephemeral --config model_reasoning_effort="low" -m gpt-6-luna` | | `opencode` | `opencode run` | | `kiro-cli` | `kiro-cli chat --no-interactive` | | `pi` | `pi --no-session -p` | | `omp` | `omp --no-session -p` | To override back to `llm` when an agent is configured, set `auto_name.command: "llm"`. ##### Configuration Optionally configure auto-name behavior in `.workmux.yaml`: ```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. Valid Git branch names are preserved, including slash-separated prefixes such as `fix/issue-123`. ```yaml auto_name: command: 'claude -p' # Force llm even when an agent is configured auto_name: command: 'llm' ``` | Option | Description | Default | | --------------- | ---------------------------------------------------------------- | -------------------------- | | `command` | Command for branch name generation (overrides agent profile) | Agent profile or `llm` CLI | | `model` | LLM model to use with the `llm` CLI (ignored when `command` set) | `llm`'s default | | `background` | Always run in background when using `--auto-name` | `false` | | `system_prompt` | Custom system prompt for branch name generation | Built-in prompt | 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 `: When used multiple times, creates one worktree for each agent. - `-n, --count `: Creates `` worktree instances. Can be combined with a single `--agent` flag to apply that agent to all instances. - `--foreach `: 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