{"slug": "parallel-development-in-tmux-with-git-worktrees", "title": "Parallel development in tmux* with Git worktrees", "summary": "Developer Raine released workmux, a command-line tool that integrates git worktrees with tmux windows to create isolated development environments for parallel workflows, including running multiple AI agents without conflict. The tool automates setup, cleanup, and branch management, and supports terminal multiplexers like tmux, kitty, WezTerm, and Zellij.", "body_md": "**Parallel development in tmux* with git worktrees**\n\n[ 📖 Documentation](https://workmux.raine.dev/) ·\n\n[Install](#installation)·\n\n[Quick start](#quick-start)·\n\n[Commands](#commands)·\n\n[Changelog](/raine/workmux/blob/main/CHANGELOG.md)\n\nGiga opinionated zero-friction workflow tool for managing\n[git worktrees](https://git-scm.com/docs/git-worktree) and tmux windows as\nisolated development environments. Perfect for running multiple AI agents in\nparallel without conflict.\n\n**Philosophy**: Build on tools you already use. tmux/zellij/kitty/etc. for\nwindowing, git for worktrees, your agent for coding - workmux ties them together.\n\n* Also supports\nkitty,\nWezTerm, and\nZellij as alternative\nbackends.\n\n📖 **New to workmux?** Read the\n[introduction blog post](https://raine.dev/blog/introduction-to-workmux/) for a\nquick overview.\n\nTip\n\nI'm building [aven](https://github.com/raine/aven), a local-first task manager\nfor power users and agents who live in the terminal.\n\n**Parallel workflows.** Work on multiple features the same time, each with its\nown AI agent. No stashing, no branch switching, no conflicts.\n\n**One window per task.** A natural mental model. Each has its own terminal\nstate, editor session, dev server, and AI agent. Context switching is switching\ntabs.\n\n**Automated setup.** New worktrees start broken (no `.env`\n\n, no `node_modules`\n\n,\nno dev server). workmux can copy config files, symlink dependencies, and run\ninstall commands on creation.\n\n**One-command cleanup.** `workmux merge`\n\nhandles the full lifecycle: merge the\nbranch, delete the worktree, close the tmux window, remove the local branch.\n\n**Terminal workflow.** Build on your terminal setup instead of yet another\nagentic GUI that won't exist next year. If you don't have one yet, tmux might be\nworth picking up.\n\nNew to worktrees? See [Why git worktrees?](#why-git-worktrees)\n\n- Create git worktrees with matching tmux windows in a single command (\n`add`\n\n) - Merge branches and clean up everything (worktree, tmux window, branches) in\none command (\n`merge`\n\n) [Dashboard](#workmux-dashboard)for monitoring agents, reviewing changes, and sending commands[Sidebar](https://workmux.raine.dev/guide/sidebar/)for a persistent, at-a-glance view of all agents across tmux windows[Delegate tasks to worktree agents](#delegating-tasks-with-worktree)with the`/worktree`\n\nskill[Display agent status in tmux window names](#agent-status-tracking)- Automatically set up your preferred tmux pane layout (editor, shell, watchers, etc.)\n- Run post-creation hooks (install dependencies, setup database, etc.)\n- Copy or symlink configuration files (\n`.env`\n\n,`node_modules`\n\n) into new worktrees [Sandbox agents](#sandbox)in containers or VMs for enhanced security[Automatic branch name generation](#automatic-branch-name-generation)from prompts using LLM- Shell completions\n\n\"I've been using (and loving) workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow.\"\n\n— @Coolin96[🔗]\n\n\"Thank you so much for your work with workmux! It's a tool I've been wanting to exist for a long time.\"\n\n— @rstacruz[🔗]\n\n\"It's become my daily driver - the perfect level of abstraction over tmux + git, without getting in the way or obscuring the underlying tooling.\"\n\n— @cisaacstern[🔗]\n\n\"I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows.\"\n\n— @dedbrizz[🔗]\n\n```\ncurl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash\nbrew install raine/workmux/workmux\n```\n\n## Other methods (Cargo, mise, Nix)\n\n**Cargo** (requires [rustup](https://rustup.rs/)):\n\n```\ncargo install workmux\n```\n\n**mise:**\n\n```\nmise use -g cargo:raine/workmux\n```\n\n**Nix** ([flake and home-manager setup](https://workmux.raine.dev/guide/nix)):\n\n```\nnix profile install github:raine/workmux\n```\n\nFor manual installation, see\n[pre-built binaries](https://github.com/raine/workmux/releases/latest).\n\nNote\n\nworkmux requires a terminal multiplexer. Make sure you have\n[tmux](https://github.com/tmux/tmux) (or\n[WezTerm](https://raine.github.io/workmux/guide/wezterm) /\n[Kitty](https://raine.github.io/workmux/guide/kitty) /\n[Zellij](https://raine.github.io/workmux/guide/zellij)) installed and running\nbefore you start. See [My tmux setup](https://raine.dev/blog/my-tmux-setup/)\nif you need a starting point.\n\n-\n**Initialize configuration (optional)**:\n\n```\nworkmux init\n```\n\nThis creates a\n\n`.workmux.yaml`\n\nfile 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. -\n**Create a new worktree and tmux window**:\n\n```\nworkmux add new-feature\n```\n\nThis will:\n\n- Create a git worktree at\n`<project_root>/../<project_name>__worktrees/new-feature`\n\n- Copy config files and symlink dependencies (if\n[configured](#file-operations)) - Run any\nsetup commands`post_create`\n\n- Create a tmux window named\n`wm-new-feature`\n\n(the prefix is configurable) - Set up your configured or the default tmux pane layout\n- Automatically switch your tmux client to the new window\n\n- Create a git worktree at\n-\n**Do your thing** -\n**Finish and clean up****Local merge:** Run`workmux merge`\n\nto 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`\n\nto clean up.\n\nworkmux uses a two-level configuration system:\n\n**Global**(`~/.config/workmux/config.yaml`\n\n): Personal defaults for all projects**Project**(`.workmux.yaml`\n\n): Project-specific overrides\n\nProject settings override global settings. When you run workmux from a\nsubdirectory, it walks upward to find the nearest `.workmux.yaml`\n\n, allowing\nnested configs for monorepos. See the\n[Monorepos guide](https://workmux.raine.dev/guide/monorepos#nested-configuration)\nfor details. For `post_create`\n\nand file operation lists (`files.copy`\n\n,\n`files.symlink`\n\n), you can use `\"<global>\"`\n\nto include global values alongside\nproject-specific ones. Other settings like `panes`\n\nare replaced entirely when\ndefined in the project config.\n\n`~/.config/workmux/config.yaml`\n\n:\n\n```\nnerdfont: true # Enable nerdfont icons (prompted on first run)\nmerge_strategy: rebase # Make workmux merge do rebase by default\nmerge_keep: true # Keep worktree, window, and branch after merge by default\nagent: claude\n\npanes:\n  - command: <agent> # Start the configured agent (e.g., claude)\n    focus: true\n  - split: horizontal # Second pane with default shell\n```\n\n`.workmux.yaml`\n\n:\n\n```\npost_create:\n  - '<global>'\n  - mise use\n\nfiles:\n  symlink:\n    - '<global>' # Include global symlinks (node_modules)\n    - .pnpm-store # Add project-specific symlink\n\npanes:\n  - command: pnpm install\n    focus: true\n  - command: <agent>\n    split: horizontal\n  - command: pnpm run dev\n    split: vertical\n```\n\nFor a real-world example, see\n[workmux's own .workmux.yaml](https://github.com/raine/workmux/blob/main/.workmux.yaml).\n\nMost options have sensible defaults. You only need to configure what you want to customize.\n\n| Option | Description | Default |\n|---|---|---|\n`main_branch` |\nBranch to merge into | Auto-detected |\n`base_branch` |\nDefault base branch for new worktrees | Current branch |\n`worktree_dir` |\nDirectory for worktrees (absolute or relative). Supports `~` and `{project}` . |\n`<project>__worktrees/` |\n`window_prefix` |\nPrefix for tmux window/session names | `wm-` |\n`mode` |\nTmux mode (`window` or `session` ) |\n`window` |\n`window_placement` |\nNew tmux window placement (`after_current` or `rightmost` ) |\n`after_current` |\n`agent` |\nDefault agent for `<agent>` placeholder |\n`claude` |\n`agents` |\nNamed agent commands (\n|\n\n`{}`\n\n`merge_strategy`\n\n`merge`\n\n, `rebase`\n\n, `squash`\n\n)`merge`\n\n`merge_keep`\n\n`workmux merge`\n\nby default`false`\n\n`theme`\n\n[custom colors](https://workmux.raine.dev/guide/configuration#custom-colors))`default`\n\n(auto dark/light)| Option | Description | Default |\n|---|---|---|\n`worktree_naming` |\nHow to derive names from branches | `full` |\n`worktree_prefix` |\nPrefix for worktree directories and windows | none |\n\n`worktree_naming`\n\nstrategies:\n\n`full`\n\n: Use the full branch name (slashes become dashes)`basename`\n\n: Use only the part after the last`/`\n\n(e.g.,`prj-123/feature`\n\n→`feature`\n\n)\n\nDefine your tmux pane layout with the `panes`\n\narray. For multiple windows in\nsession mode, use [ windows](#multiple-windows-per-session) instead (they are\nmutually exclusive).\n\n```\npanes:\n  - command: <agent>\n    focus: true\n  - command: npm run dev\n    split: horizontal\n    size: 15\n```\n\nEach pane supports:\n\n| Option | Description | Default |\n|---|---|---|\n`command` |\nCommand to run (see\n|\n\n`focus`\n\n`false`\n\n`zoom`\n\n`focus: true`\n\n)`false`\n\n`split`\n\n`horizontal`\n\nor `vertical`\n\n)`size`\n\n`percentage`\n\n`<agent>`\n\n: resolves to the configured agent (from`agent`\n\nconfig or`--agent`\n\nflag)\n\nBuilt-in agents (`claude`\n\n, `gemini`\n\n, `codex`\n\n, `opencode`\n\n, `kiro-cli`\n\n, `vibe`\n\n,\n`pi`\n\n, `omp`\n\n) are auto-detected when used as literal commands and receive prompt\ninjection automatically, without needing the `<agent>`\n\nplaceholder or a matching\n`agent`\n\nconfig:\n\n```\npanes:\n  - command: 'claude --dangerously-skip-permissions'\n    focus: true\n  - command: 'codex --yolo'\n    split: vertical\n```\n\nEach agent receives the prompt (via `-p`\n\n/`-P`\n\n/`-e`\n\n) using the correct format for\nthat agent. Auto-detection matches the executable name regardless of flags or\npath.\n\nDefine reusable pane arrangements in the `layouts`\n\nmap and select one at\nadd-time with `-l/--layout`\n\n:\n\n```\nlayouts:\n  design:\n    panes:\n      - command: <agent>\n        focus: true\n      - command: <agent:codex>\n        split: vertical\n  review:\n    panes:\n      - command: <agent>\nworkmux add my-feature -l design\n```\n\nWhen `-l`\n\nis used, the layout's `panes`\n\nreplace the top-level `panes`\n\nfor that\nworktree. All other config (hooks, files, agent, etc.) comes from the top-level\nas usual. The `-l`\n\nflag cannot be combined with `--agent`\n\n.\n\nNew worktrees are clean checkouts with no gitignored files (`.env`\n\n,\n`node_modules`\n\n, etc.). Use `files`\n\nto automatically copy or symlink what each\nworktree needs:\n\n```\nfiles:\n  copy:\n    - .env\n  symlink:\n    - .next/cache # Share build cache across worktrees\n```\n\nBoth `copy`\n\nand `symlink`\n\naccept glob patterns.\n\nTo re-apply file operations to an existing worktree (e.g., after updating the\nconfig), run `workmux sync-files`\n\nfrom inside the worktree. Use `--all`\n\nto sync\nall worktrees at once.\n\nRun commands at specific points in the worktree lifecycle, such as installing\ndependencies or running database migrations. All hooks run with the **worktree\ndirectory** as the working directory (or the nested config directory for\n[nested configs](https://workmux.raine.dev/guide/monorepos#nested-configuration))\nand receive environment variables: `WM_HANDLE`\n\n, `WM_WORKTREE_PATH`\n\n,\n`WM_PROJECT_ROOT`\n\n, `WM_CONFIG_DIR`\n\n.\n\n`WM_CONFIG_DIR`\n\npoints to the directory containing the `.workmux.yaml`\n\nthat was\nused, which may differ from `WM_WORKTREE_PATH`\n\nwhen using nested configs.\n\n| Hook | When it runs | Additional env vars |\n|---|---|---|\n`post_create` |\nAfter worktree creation, before tmux window opens | — |\n`pre_merge` |\nBefore merging (aborts on failure) | `WM_BRANCH_NAME` , `WM_TARGET_BRANCH` |\n`pre_remove` |\nBefore worktree removal (aborts on failure) | — |\n\nExample:\n\n```\npost_create:\n  - direnv allow\n\npre_merge:\n  - just check\n```\n\nCustomize the icons shown in tmux window names:\n\n```\nstatus_icons:\n  working: '🤖' # Agent is processing\n  waiting: '💬' # Agent needs input (auto-clears on focus)\n  done: '✅' # Agent finished (auto-clears on focus)\n```\n\nAgents in \"working\" status that produce no pane output for 10 seconds are automatically detected as interrupted.\n\nSet `status_format: false`\n\nto disable automatic tmux format modification\n\n- Worktrees are created in\n`<project>__worktrees`\n\nas a sibling directory to your project by default - If no\n`panes`\n\nconfiguration is defined, workmux provides opinionated defaults:- For projects with a\n`CLAUDE.md`\n\nfile: Opens the configured agent (see`agent`\n\noption) in the first pane, defaulting to`claude`\n\nif none is set. - For all other projects: Opens your default shell.\n- Both configurations include a second pane split horizontally\n\n- For projects with a\n`post_create`\n\ncommands are optional and only run if you configure them\n\nUse the `panes`\n\nconfiguration to automate environment setup. Unlike\n`post_create`\n\nhooks which must finish before the tmux window opens, pane\ncommands execute immediately *within* the new window.\n\nThis can be used for:\n\n**Installing dependencies**: Run`npm install`\n\nor`cargo build`\n\nin 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.\n\nSince these run in standard tmux panes, you can interact with them (check logs, restart servers) just like a normal terminal session.\n\nRunning dependency installation (like `pnpm install`\n\n) in a pane command rather\nthan `post_create`\n\nhas a key advantage: you get immediate access to the tmux\nwindow while installation runs in the background. With `post_create`\n\n, you'd have\nto wait for the install to complete before the window even opens. This also\nmeans AI agents can start working immediately in their pane while dependencies\ninstall in parallel.\n\n```\npanes:\n  # Pane 1: Install dependencies, then start dev server\n  - command: pnpm install && pnpm run dev\n\n  # Pane 2: AI agent\n  - command: <agent>\n    split: horizontal\n    focus: true\n```\n\nHere's how workmux organizes your worktrees by default:\n\n```\n~/projects/\n├── my-project/               <-- Main project directory\n│   ├── src/\n│   ├── package.json\n│   └── .workmux.yaml\n│\n└── my-project__worktrees/    <-- Worktrees created by workmux\n    ├── feature-A/            <-- Isolated workspace for 'feature-A' branch\n    │   ├── src/\n    │   └── package.json\n    │\n    └── bugfix-B/             <-- Isolated workspace for 'bugfix-B' branch\n        ├── src/\n        └── package.json\n```\n\nEach 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.\n\nYou can customize the worktree directory location using the `worktree_dir`\n\nconfiguration option (see [Configuration options](#configuration-options)).\nThe value supports `~`\n\nfor the home directory and a `{project}`\n\nplaceholder\nthat resolves to the main worktree's directory name. This lets a single\nglobal config namespace every repo's worktrees under one root, e.g.\n`worktree_dir: ~/.workmux/{project}`\n\n.\n\nFor faster typing, alias `workmux`\n\nto `wm`\n\n:\n\n```\nalias wm='workmux'\n```\n\n- Create a new worktree and tmux window`add`\n\n- Merge a branch and clean up everything`merge`\n\n- Rebase a worktree branch onto its base branch`rebase`\n\n- Remove worktrees without merging`remove`\n\n- List all worktrees with status`list`\n\n- Open a tmux window for an existing worktree`open`\n\n- Close a worktree's tmux window (keeps worktree)`close`\n\n- Restore worktree windows after a crash`resurrect`\n\n- Get the filesystem path of a worktree`path`\n\n- Show TUI dashboard of all active agents`dashboard`\n\n- Toggle a compact agent status sidebar in tmux`sidebar`\n\n- Exit tracked agent processes older than a threshold`reap-agents`\n\n- Edit the global configuration file`config edit`\n\n- Generate configuration file`init`\n\n- Manage sandbox backends (container/Lima)`sandbox`\n\n- Clean up stale Claude Code entries`claude prune`\n\n- Generate shell completions`completions`\n\n- Show detailed documentation`docs`\n\nCreates 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.\n\n`<branch-name>`\n\n: Name of the branch to create or switch to, a remote branch reference (e.g.,`origin/feature-branch`\n\n), or a GitHub fork reference (e.g.,`user:branch`\n\n). 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`\n\n(e.g.,`someuser:feature`\n\ncreates local branch`someuser-feature`\n\n). Optional when using`--pr`\n\n.\n\n`--base <branch|commit|tag>`\n\n: Specify a base branch, commit, or tag to branch from when creating a new branch. Overrides`base_branch`\n\nconfig. Defaults to`base_branch`\n\nfrom config, then the currently checked out branch.`--pr <number>`\n\n: Checkout a GitHub pull request by its number into a new worktree.- Requires the\n`gh`\n\ncommand-line tool to be installed and authenticated. - The local branch name defaults to the PR's head branch name, but can be\noverridden (e.g.,\n`workmux add custom-name --pr 123`\n\n). - If that local branch already exists and has no worktree, it is reused.\n\n- Requires the\n`-A, --auto-name`\n\n: Generate branch name from prompt using LLM. See[Automatic branch name generation](#automatic-branch-name-generation).`--name <name>`\n\n: 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`\n\n,`--foreach`\n\n, or multiple`--agent`\n\n).`-b, --background`\n\n: Create the tmux window in the background without switching to it. Useful with`--prompt-editor`\n\n.`-w, --with-changes`\n\n: 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`\n\n: Interactively select which changes to move (requires`--with-changes`\n\n). Opens an interactive prompt for selecting hunks to stash.`-u, --include-untracked`\n\n: Also move untracked files (requires`--with-changes`\n\n). By default, only staged and modified tracked files are moved.`-p, --prompt <text>`\n\n: Provide an inline prompt that will be automatically passed to AI agent panes.`-P, --prompt-file <path>`\n\n: Provide a path to a file whose contents will be used as the prompt.`-e, --prompt-editor`\n\n: Open your`$EDITOR`\n\n(or`$VISUAL`\n\n) to write the prompt interactively.`--prompt-file-only`\n\n: 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`\n\ndirectly.`-l, --layout <name>`\n\n: Use a named pane layout from config instead of the default panes. Cannot be combined with`--agent`\n\n.`-a, --agent <name>`\n\n: The agent(s) to use for the worktree(s). Can be specified multiple times to generate a worktree for each agent. Overrides the`agent`\n\nfrom your config file.`-W, --wait`\n\n: 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`\n\n.`-o, --open-if-exists`\n\n: If a worktree for the branch already exists, open it instead of failing. Similar to`tmux new-session -A`\n\n. Useful when you don't know or care whether the worktree already exists.`-s, --session`\n\n: Create a tmux session instead of a window. See[Session mode](#session-mode)for details.`--config <path>`\n\n: Use an alternate config file for this invocation. Still merges with global config.`--fork`\n\n: Fork the last conversation from the current worktree into the new one. The agent resumes with the forked conversation context. Use`--fork=<session-id>`\n\nto fork a specific session (prefix matching supported). Currently supports Claude Code.\n\nThese options allow you to skip expensive setup steps when they're not needed (e.g., for documentation-only changes):\n\n`-H, --no-hooks`\n\n: Skip running`post_create`\n\ncommands`-F, --no-file-ops`\n\n: Skip file copy/symlink operations (e.g., skip linking`node_modules`\n\n)`-C, --no-pane-cmds`\n\n: Skip executing pane commands (panes open with plain shells instead)\n\n- Determines the\n**handle** for the worktree by slugifying the branch name (e.g.,`feature/auth`\n\nbecomes`feature-auth`\n\n). This can be overridden with the`--name`\n\nflag. - Creates a git worktree at\n`<worktree_dir>/<handle>`\n\n(the`worktree_dir`\n\nis configurable and defaults to a sibling directory of your project) - Runs any configured file operations (copy/symlink)\n- Executes\n`post_create`\n\ncommands if defined (runs before the tmux window opens, so keep them fast) - Creates a new tmux window named\n`<window_prefix><handle>`\n\n(e.g.,`wm-feature-auth`\n\nwith`window_prefix: wm-`\n\n) - Sets up your configured tmux pane layout\n- Automatically switches your tmux client to the new window\n\n```\n# Create a new branch and worktree\nworkmux add user-auth\n\n# Use an existing branch\nworkmux add existing-work\n\n# Create a new branch from a specific base\nworkmux add hotfix --base production\n\n# Create a worktree from a remote branch (creates local branch \"user-auth-pr\")\nworkmux add origin/user-auth-pr\n\n# Remote branches with slashes work too (creates local branch \"feature/foo\")\nworkmux add origin/feature/foo\n\n# Create a worktree in the background without switching to it\nworkmux add feature/parallel-task --background\n\n# Use a custom name for the worktree directory and tmux window\nworkmux add feature/long-descriptive-branch-name --name short\n\n# Open existing worktree if it exists, create if it doesn't (idempotent)\nworkmux add my-feature -o\n# Checkout PR #123. The local branch will be named after the PR's branch.\nworkmux add --pr 123\n\n# Checkout PR #456 with a custom local branch name\nworkmux add fix/api-bug --pr 456\n\n# Checkout a fork branch using GitHub's owner:branch format (copy from GitHub UI)\n# Creates local branch \"someuser-feature-branch\" tracking the fork\nworkmux add someuser:feature-branch\n# Move uncommitted changes to a new worktree (including untracked files)\nworkmux add feature/new-thing --with-changes -u\n\n# Move only staged/modified files (not untracked files)\nworkmux add fix/bug --with-changes\n\n# Interactively select which changes to move\nworkmux add feature/partial --with-changes --patch\n# Create a worktree with an inline prompt for AI agents\nworkmux add feature/ai --prompt \"Implement user authentication with OAuth\"\n\n# Override the default agent for a specific worktree\nworkmux add feature/testing -a gemini\n\n# Create a worktree with a prompt from a file\nworkmux add feature/refactor --prompt-file task-description.md\n\n# Open your editor to write a prompt interactively\nworkmux add feature/new-api --prompt-editor\n\n# Write prompt file only (for editors with embedded agents like neovim)\nworkmux add feature/task -P task.md --prompt-file-only\n# Skip expensive setup for documentation-only changes\nworkmux add docs-update --no-hooks --no-file-ops --no-pane-cmds\n\n# Skip just the file operations (e.g., you don't need node_modules)\nworkmux add quick-fix --no-file-ops\n# Block until the agent completes and closes the window\nworkmux add feature/api --wait -p \"Implement the REST API, then run: workmux remove --keep-branch\"\n\n# Use in a script to run sequential agent tasks\nfor task in task1.md task2.md task3.md; do\n  workmux add \"task-$(basename $task .md)\" --wait -P \"$task\"\ndone\n```\n\nWhen you provide a prompt via `--prompt`\n\n, `--prompt-file`\n\n, or `--prompt-editor`\n\n,\nworkmux automatically injects the prompt into panes running the configured agent\ncommand (e.g., `claude`\n\n, `codex`\n\n, `opencode`\n\n, `gemini`\n\n, `kiro-cli`\n\n, `vibe`\n\n,\n`pi`\n\n, `omp`\n\n, or whatever you've set via the `agent`\n\nconfig or `--agent`\n\nflag) without\nrequiring any `.workmux.yaml`\n\nchanges:\n\n- Panes with a command matching the configured agent are automatically started with the given prompt.\n- You can keep your\n`.workmux.yaml`\n\npane configuration simple (e.g.,`panes: [{ command: \"<agent>\" }]`\n\n) and let workmux handle prompt injection at runtime.\n\nThis means you can launch AI agents with task-specific prompts without modifying your project configuration for each task.\n\nIf your editor has an embedded agent (e.g., neovim with an agent plugin), use\n`--prompt-file-only`\n\nto write the prompt to `.workmux/PROMPT-<branch>.md`\n\nwithout requiring an agent pane. Your editor can then detect and consume the\nfile on startup. This can also be set permanently in config with\n`prompt_file_only: true`\n\n.\n\nThe `--auto-name`\n\n(`-A`\n\n) flag generates a branch name from your prompt using an\nLLM. The tool used depends on your configuration:\n\n`auto_name.command`\n\nis set: uses that command as-is`config.agent`\n\nis a known agent (`claude`\n\n,`gemini`\n\n,`codex`\n\n,`opencode`\n\n,`kiro-cli`\n\n,`vibe`\n\n,`pi`\n\n,`omp`\n\n): uses the agent's CLI with a fast/cheap model- Neither: falls back to the\nCLI tool`llm`\n\n```\n# Opens editor for prompt, generates branch name\nworkmux add -A\n\n# With inline prompt\nworkmux add -A -p \"Add OAuth authentication\"\n\n# With prompt file\nworkmux add -A -P task-spec.md\n```\n\nWhen `agent`\n\nis configured (e.g., `agent: claude`\n\n), workmux automatically uses\nthat agent's CLI for branch naming. No additional setup is required beyond\nhaving the agent installed.\n\nIf no agent is configured and no `auto_name.command`\n\nis set, workmux uses the\n`llm`\n\nCLI tool:\n\n```\npipx install llm\n```\n\nConfigure a model (e.g., OpenAI):\n\n```\nllm keys set openai\n# Or use a local model\nllm install llm-ollama\n```\n\nIf you set `auto_name.command`\n\n, `llm`\n\nis not required.\n\nWhen an agent is configured, these commands are used automatically:\n\n| Agent | Auto-name command |\n|---|---|\n`claude` |\n`claude --model haiku -p` |\n`gemini` |\n`gemini -m gemini-2.5-flash-lite -p` |\n`codex` |\n`codex exec --config model_reasoning_effort=\"low\" -m gpt-5.1-codex-mini` |\n`opencode` |\n`opencode run` |\n`kiro-cli` |\n`kiro-cli chat --no-interactive` |\n`pi` |\n`pi -p` |\n`omp` |\n`omp -p` |\n\nTo override back to `llm`\n\nwhen an agent is configured, set\n`auto_name.command: \"llm\"`\n\n.\n\nOptionally configure auto-name behavior in `.workmux.yaml`\n\n:\n\n```\nauto_name:\n  model: 'gemini-2.5-flash-lite'\n  background: true # Always run in background when using --auto-name\n  system_prompt: |\n    Generate a concise git branch name based on the task description.\n\n    Rules:\n    - Use kebab-case (lowercase with hyphens)\n    - Keep it short: 1-3 words, max 4 if necessary\n    - Focus on the core task/feature, not implementation details\n    - No prefixes like feat/, fix/, chore/\n\n    Examples of good branch names:\n    - \"Add dark mode toggle\" → dark-mode\n    - \"Fix the search results not showing\" → fix-search\n    - \"Refactor the authentication module\" → auth-refactor\n    - \"Add CSV export to reports\" → export-csv\n    - \"Shell completion is broken\" → shell-completion\n\n    Output ONLY the branch name, nothing else.\n```\n\nTo use a specific tool, set `auto_name.command`\n\n. The command string is split\ninto program and arguments, and the composed prompt is piped via stdin.\n\n```\nauto_name:\n  command: 'claude -p'\n\n# Force llm even when an agent is configured\nauto_name:\n  command: 'llm'\n```\n\n| Option | Description | Default |\n|---|---|---|\n`command` |\nCommand for branch name generation (overrides agent profile) | Agent profile or `llm` CLI |\n`model` |\nLLM model to use with the `llm` CLI (ignored when `command` set) |\n`llm` 's default |\n`background` |\nAlways run in background when using `--auto-name` |\n`false` |\n`system_prompt` |\nCustom system prompt for branch name generation | Built-in prompt |\n\nRecommended models for fast, cheap branch name generation (with `llm`\n\n):\n\n`gemini-2.5-flash-lite`\n\n(recommended)`gpt-5-nano`\n\nworkmux can generate multiple worktrees from a single `add`\n\ncommand, which is\nideal for running parallel experiments or delegating tasks to multiple AI\nagents. This is controlled by four mutually exclusive modes:\n\n- (\n`-a`\n\n,`--agent`\n\n): Create a worktree for each specified agent. - (\n`-n`\n\n,`--count`\n\n): Create a specific number of worktrees. - (\n`--foreach`\n\n): Create worktrees based on a matrix of variables. **stdin**: Pipe input lines to create worktrees with templated prompts.\n\nWhen using any of these modes, branch names are generated from a template, and\nprompts are templated with variables. Single-worktree prompts are passed through\nliterally, so common syntax like GitHub Actions `${{ ... }}`\n\ndoes not need to be\nescaped.\n\n`-a, --agent <name>`\n\n: When used multiple times, creates one worktree for each agent.`-n, --count <number>`\n\n: Creates`<number>`\n\nworktree instances. Can be combined with a single`--agent`\n\nflag to apply that agent to all instances.`--foreach <matrix>`\n\n: Creates worktrees from a variable matrix string. The format is`\"var1:valA,valB;var2:valX,valY\"`\n\n. 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>`\n\n: A[MiniJinja](https://docs.rs/minijinja/latest/minijinja/)(Jinja2-compatible) template for generating branch names.- Available variables:\n`{{ base_name }}`\n\n,`{{ agent }}`\n\n,`{{ num }}`\n\n,`{{ index }}`\n\n,`{{ input }}`\n\n(stdin), and any variables from`--foreach`\n\n. - Default:\n`{{ base_name }}{% if agent %}-{{ agent | slugify }}{% endif %}{% for key, value in foreach_vars %}-{{ value | slugify }}{% endfor %}{% if num %}-{{ num }}{% endif %}`\n\n- Available variables:\n`--max-concurrent <number>`\n\n: Limits how many worktrees run simultaneously. When set, workmux creates up to`<number>`\n\nworktrees, 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`\n\n).\n\nWhen generating multiple worktrees, any prompt provided via `-p`\n\n, `-P`\n\n, or `-e`\n\nis treated as a MiniJinja template. You can use variables from your generation\nmode to create unique prompts for each agent or instance. For ordinary\nsingle-worktree `add`\n\ncommands, prompt text is not templated.\n\nInstead of passing `--foreach`\n\non the command line, you can specify the variable\nmatrix directly in your prompt file using YAML frontmatter. This is more\nconvenient for complex matrices and keeps the variables close to the prompt that\nuses them.\n\n**Format:**\n\nCreate a prompt file with YAML frontmatter at the top, separated by `---`\n\n:\n\n**Example 1:** `mobile-task.md`\n\n```\n---\nforeach:\n  platform: [iOS, Android]\n  lang: [swift, kotlin]\n---\n\nBuild a {{ platform }} app using {{ lang }}. Implement user authentication and\ndata persistence.\nworkmux add mobile-app --prompt-file mobile-task.md\n# Generates worktrees: mobile-app-ios-swift, mobile-app-android-kotlin\n```\n\n**Example 2:** `agent-task.md`\n\n(using `agent`\n\nas a foreach variable)\n\n```\n---\nforeach:\n  agent: [claude, gemini]\n---\n\nImplement the dashboard refactor using your preferred approach.\nworkmux add refactor --prompt-file agent-task.md\n# Generates worktrees: refactor-claude, refactor-gemini\n```\n\n**Behavior:**\n\n- Variables from the frontmatter are available in both the prompt template and the branch name template\n- All value lists must have the same length, and values are paired by index\nposition (same zip behavior as\n`--foreach`\n\n) - CLI\n`--foreach`\n\noverrides frontmatter with a warning if both are present - Works with both\n`--prompt-file`\n\nand`--prompt-editor`\n\nYou can pipe input lines to `workmux add`\n\nto create multiple worktrees. Each\nline becomes available as the `{{ input }}`\n\ntemplate variable in your prompt.\nThis is useful for batch-processing tasks from external sources.\n\n**Plain text:** Each line becomes `{{ input }}`\n\n```\necho -e \"api\\nauth\\ndatabase\" | workmux add refactor -P task.md\n# {{ input }} = \"api\", \"auth\", \"database\"\n```\n\n**JSON lines:** Each key becomes a template variable\n\n```\ngh repo list --json url,name --jq -c '.[]' | workmux add analyze \\\n  --branch-template '{{ base_name }}-{{ name }}' \\\n  -P prompt.md\n# Line: {\"url\":\"https://github.com/raine/workmux\",\"name\":\"workmux\"}\n# Variables: {{ url }}, {{ name }}, {{ input }} (raw JSON line)\n```\n\nThis lets you structure data upstream with `jq`\n\nand use meaningful branch names\nwhile keeping the full URL available in your prompt.\n\n**Behavior:**\n\n- Empty lines and whitespace-only lines are filtered out\n- Stdin input cannot be combined with\n`--foreach`\n\n(mutually exclusive) - JSON objects (lines starting with\n`{`\n\n) are parsed and each key becomes a variable `{{ input }}`\n\nalways contains the raw line- If JSON contains an\n`input`\n\nkey, it overwrites the raw line value\n\n```\n# Create one worktree for claude and one for gemini with a focused prompt\nworkmux add my-feature -a claude -a gemini -p \"Implement the new search API integration\"\n# Generates worktrees: my-feature-claude, my-feature-gemini\n\n# Create 2 instances of the default agent\nworkmux add my-feature -n 2 -p \"Implement task #{{ num }} in TASKS.md\"\n# Generates worktrees: my-feature-1, my-feature-2\n\n# Create worktrees from a variable matrix\nworkmux add my-feature --foreach \"platform:iOS,Android\" -p \"Build for {{ platform }}\"\n# Generates worktrees: my-feature-ios, my-feature-android\n\n# Create agent-specific worktrees via --foreach\nworkmux add my-feature --foreach \"agent:claude,gemini\" -p \"Implement the dashboard refactor\"\n# Generates worktrees: my-feature-claude, my-feature-gemini\n\n# Use frontmatter in a prompt file for cleaner syntax\n# task.md contains:\n# ---\n# foreach:\n#   env: [staging, production]\n#   task: [smoke-tests, integration-tests]\n# ---\n# Run {{ task }} against the {{ env }} environment\nworkmux add testing --prompt-file task.md\n# Generates worktrees: testing-staging-smoke-tests, testing-production-integration-tests\n\n# Pipe input from stdin to create worktrees\n# review.md contains: Review the {{ input }} module for security issues.\necho -e \"auth\\npayments\\napi\" | workmux add review -A -P review.md\n# Generates worktrees with LLM-generated branch names for each module\n```\n\nCombine stdin input, prompt templating, and concurrency limits to create a worker pool that processes items from an external command.\n\n**Example: Generate test scaffolding for untested files**\n\n```\n# generate-tests.md contains:\n# Read the file at {{ input }} and generate a test suite covering\n# the exported functions. Focus on happy path and edge cases.\n# When done, run: workmux remove --keep-branch\n\nfind src/utils -name \"*.ts\" ! -name \"*.test.ts\" | \\\n  workmux add add-tests \\\n    --branch-template '{{ base_name }}-{{ index }}' \\\n    --prompt-file generate-tests.md \\\n    --max-concurrent 3 \\\n    --background\n```\n\n`find ...`\n\nlists files without tests (one per line) piped to stdin`--branch-template`\n\nuses`{{ index }}`\n\nfor unique branch names`--prompt-file`\n\nuses`{{ input }}`\n\nto pass each file path to the agent`--max-concurrent 3`\n\nlimits parallel agents to avoid rate limits`--background`\n\nruns without switching focus\n\nMerges a branch into a target branch (main by default) and automatically cleans up all associated resources (worktree, tmux window, and local branch).\n\nTip\n\n** merge vs remove**: Use\n\n`merge`\n\nwhen you want to merge directly\nwithout a pull request. If your workflow uses pull requests, use\n[to clean up after your PR is merged on the remote.](#workmux-remove-name-alias-rm)\n\n`remove`\n\n`[branch-name]`\n\n: Optional name of the branch to merge. If omitted, automatically detects the current branch from the worktree you're in.\n\n`--into <branch>`\n\n: 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`\n\n: Commit any staged changes before merging without opening an editor`--keep`\n\n,`-k`\n\n: Keep the worktree, window, and branch after merging (skip cleanup). Useful when you want to verify the merge before cleaning up.`--cleanup`\n\n: Clean up after merging, overriding`merge_keep: true`\n\n.`--notification`\n\n: Show a system notification on successful merge. Useful when delegating merge to an AI agent and you want to be notified when it completes.\n\nBy default, `workmux merge`\n\nperforms a standard merge commit (configurable via\n`merge_strategy`\n\n). You can override the configured behavior with these mutually\nexclusive flags:\n\n`--rebase`\n\n: 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`\n\n.`--squash`\n\n: 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.\n\nIf you don't want to have merge commits in your main branch, use the `rebase`\n\nmerge strategy, which does `--rebase`\n\nby default.\n\n```\n# ~/.config/workmux/config.yaml\nmerge_strategy: rebase\n```\n\nTo keep the worktree, window, and branch after every merge unless overridden, set:\n\n```\nmerge_keep: true\n```\n\nUse `workmux merge --cleanup`\n\nto clean up for a single merge when this default is\nenabled.\n\n- Determines which branch to merge (specified branch or current branch if omitted)\n- Determines the target branch (\n`--into`\n\nor main branch from config) - Checks for uncommitted changes (errors if found, unless\n`--ignore-uncommitted`\n\nis used) - Commits staged changes if present (unless\n`--ignore-uncommitted`\n\nis used) - Merges your branch into the target using the selected strategy (default: merge commit)\n- Deletes the tmux window unless keep behavior is enabled via\n`--keep`\n\nor`merge_keep: true`\n\n- Removes the worktree unless keep behavior is enabled via\n`--keep`\n\nor`merge_keep: true`\n\n- Deletes the local branch unless keep behavior is enabled via\n`--keep`\n\nor`merge_keep: true`\n\nWhen you're done working in a worktree, simply run `workmux merge`\n\nfrom within\nthat worktree's tmux window. The command will automatically detect which branch\nyou're on, merge it into main, and close the current window as part of cleanup.\n\n```\n# Merge branch into main (default: merge commit)\nworkmux merge user-auth\n\n# Merge the current worktree you're in\n# (run this from within the worktree's tmux window)\nworkmux merge\n\n# Rebase onto main before merging for a linear history\nworkmux merge user-auth --rebase\n\n# Squash all commits into a single commit\nworkmux merge user-auth --squash\n\n# Merge but keep the worktree/window/branch to verify before cleanup\nworkmux merge user-auth --keep\n# ... verify the merge in main ...\nworkmux remove user-auth  # clean up later when ready\n\n# Merge into a different branch (stacked PRs)\nworkmux merge feature/subtask --into feature/parent\n```\n\nRebases 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.\n\n`[name]`\n\n: Optional worktree name or branch. If omitted, workmux detects the current worktree from the current directory.\n\n- Determines which worktree branch to rebase\n- Reads the saved base branch recorded when the worktree was created\n- Falls back to the configured main branch when the saved base is not a local branch\n- Runs\n`git rebase <base>`\n\ninside the worktree - Leaves the worktree, window, and branch in place\n\n```\nworkmux rebase user-auth\nworkmux rebase\n```\n\nRemoves 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.\n\n`[name]...`\n\n: One or more worktree names (the directory names). Defaults to current directory name if omitted.\n\n`--all`\n\n: Remove all worktrees at once (except the main worktree). Prompts for confirmation unless`--force`\n\nis used. Safely skips worktrees with uncommitted changes or unmerged commits.`--gone`\n\n: Remove worktrees whose upstream remote branch has been deleted (e.g., after a PR is merged on GitHub). Automatically runs`git fetch --prune`\n\nfirst.`--force`\n\n,`-f`\n\n: Skip confirmation prompt and ignore uncommitted changes`--keep-branch`\n\n,`-k`\n\n: Remove only the worktree and tmux window while keeping the local branch\n\n```\n# Remove the current worktree (run from within the worktree)\nworkmux remove\n\n# Remove a specific worktree with confirmation if unmerged\nworkmux remove experiment\n\n# Remove multiple worktrees at once\nworkmux rm feature-a feature-b feature-c\n\n# Remove multiple worktrees with force (no confirmation)\nworkmux rm -f old-work stale-branch\n\n# Use the alias\nworkmux rm old-work\n\n# Remove worktree/window but keep the branch\nworkmux remove --keep-branch experiment\n\n# Force remove without prompts\nworkmux rm -f experiment\n\n# Remove worktrees whose remote branches were deleted (e.g., after PR merge)\nworkmux rm --gone\n\n# Force remove all gone worktrees (no confirmation)\nworkmux rm --gone -f\n\n# Remove all worktrees at once\nworkmux rm --all\n```\n\nRenames a worktree's directory, its tmux window or session, and the per-worktree workmux metadata. Optionally also renames the underlying git branch.\n\n`[old-name]`\n\n: Optional current worktree name. Defaults to the current worktree when run from inside one.`<new-name>`\n\n: The new handle (directory name and tmux window/session base name).\n\n`--branch`\n\n,`-b`\n\n: Also rename the underlying git branch to match`<new-name>`\n\n. Fails if the worktree is on a detached HEAD.\n\n```\n# Rename a worktree from inside it\nworkmux rename feature-new\n\n# Rename a specific worktree by name\nworkmux rename feature-old feature-new\n\n# Also rename the branch to match\nworkmux rename feature-old feature-new --branch\n```\n\nRename 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.\n\nLists all git worktrees with their agent status, multiplexer window status, and merge status. Supports filtering by worktree handle or branch name.\n\n`[worktree-or-branch...]`\n\n: Filter by worktree handle (directory name) or branch name. Accepts multiple values. When omitted, shows all worktrees.\n\n`--pr`\n\n: Show GitHub PR status for each worktree. Requires the`gh`\n\nCLI to be installed and authenticated. Note that it shows pull requests' statuses with[Nerd Font](https://www.nerdfonts.com/)icons, which requires Nerd Font compatible font installed.`--json`\n\n: Output as JSON. Produces a JSON array of objects with fields:`handle`\n\n,`branch`\n\n,`path`\n\n,`is_main`\n\n,`mode`\n\n,`has_uncommitted_changes`\n\n,`is_open`\n\n,`created_at`\n\n.\n\n```\n# List all worktrees\nworkmux list\n\n# List with PR status\nworkmux list --pr\n\n# Output as JSON for scripting\nworkmux list --json\n\n# Filter to specific worktrees\nworkmux list my-feature\nworkmux list feature-auth feature-api\nBRANCH      AGE  AGENT  MUX  UNMERGED  PATH\nmain        -    -      -    -         ~/project\nuser-auth   2h   🤖     ✓    -         ~/project__worktrees/user-auth\nbug-fix     3d   ✅     ✓    ●         ~/project__worktrees/bug-fix\napi-work    1w   -      ✓    -         ~/project__worktrees/api-work\n```\n\n- AGE shows how old the worktree is (e.g.,\n`2h`\n\n,`3d`\n\n,`1w`\n\n,`2mo`\n\n) - AGENT shows the current agent status (see\n[status tracking](https://workmux.dev/guide/status-tracking/)):`🤖`\n\n= working,`💬`\n\n= waiting for input,`✅`\n\n= finished- Multiple agents per worktree show a count (e.g.,\n`2🤖 1✅`\n\n)\n\n`✓`\n\nin MUX column = multiplexer window exists for this worktree`●`\n\nin UNMERGED column = branch has commits not merged into main`-`\n\n= not applicable\n\nOpens the global configuration file (`~/.config/workmux/config.yaml`\n\n) in your\npreferred editor. Uses `$VISUAL`\n\n, `$EDITOR`\n\n, or falls back to `vi`\n\n. Creates the\nfile with commented-out defaults if it doesn't exist yet.\n\nPrints the path to the global configuration file. Useful for scripting.\n\nPrints the default configuration file with all options documented. Useful for discovering available options or piping to an AI agent for context.\n\nGenerates `.workmux.yaml`\n\nwith example configuration and `\"<global>\"`\n\nplaceholder usage.\n\nOpens or switches to a tmux window for a pre-existing git worktree. If the window already exists, switches to it. If not, creates a new window with the configured pane layout and environment. Accepts multiple names to open several worktrees at once.\n\n`[name...]`\n\n: One or more worktree names (the directory name, which is also the tmux window name without the prefix). Optional with`--new`\n\nwhen run from inside a worktree.\n\n`-n, --new`\n\n: Force opening in a new window even if one already exists. Creates a duplicate window with a suffix (e.g.,`-2`\n\n,`-3`\n\n). Useful for having multiple terminal views into the same worktree. In tmux, the duplicate appears immediately to the right of the window where the command runs.`-s, --session`\n\n: Open in session mode, overriding the stored mode. Persists the mode change for subsequent opens. Cannot be combined with`--new`\n\n. Only supported with tmux.`--config <path>`\n\n: Use an alternate config file for this invocation. Still merges with global config.`--run-hooks`\n\n: Re-runs the`post_create`\n\ncommands (these block window creation).`--force-files`\n\n: Re-applies file copy/symlink operations. Useful for restoring a deleted`.env`\n\nfile.`-p, --prompt <text>`\n\n: Provide an inline prompt for AI agent panes.`-P, --prompt-file <path>`\n\n: Provide a path to a file containing the prompt.`-c, --continue`\n\n: Resume the agent's most recent conversation in this worktree. Injects the appropriate flag for the configured agent (e.g.,`--continue`\n\nfor Claude,`--resume`\n\nfor Gemini).`-e, --prompt-editor`\n\n: Open your editor to write the prompt interactively.`--prompt-file-only`\n\n: Write the prompt file without injecting it into agent commands.\n\n- Verifies that a worktree with\n`<name>`\n\nexists. - If a tmux window exists and\n`--new`\n\nis not set, switches to it. - Otherwise, creates a new tmux window (with suffix if duplicating). In tmux, duplicate windows appear immediately to the right of the window where the command runs.\n- (If specified) Runs file operations and\n`post_create`\n\nhooks. - Sets up your configured tmux pane layout.\n- Automatically switches your tmux client to the new window.\n\n```\n# Open or switch to a window for an existing worktree\nworkmux open user-auth\n\n# Force open a second window for the same worktree (creates user-auth-2)\nworkmux open user-auth --new\n\n# Open a new window for the current worktree (run from within the worktree)\nworkmux open --new\n\n# Open in session mode (converts from window mode if needed)\nworkmux open user-auth --session\n\n# Resume the agent's last conversation\nworkmux open user-auth --continue\n\n# Resume and send a follow-up prompt\nworkmux open user-auth --continue -p \"Continue implementing the login flow\"\n\n# Open and re-run dependency installation\nworkmux open user-auth --run-hooks\n\n# Open and restore configuration files\nworkmux open user-auth --force-files\n\n# Open multiple worktrees at once\nworkmux open user-auth api-refactor bugfix-login\n```\n\nCloses the tmux window for a worktree without removing the worktree or branch. This is useful when you want to temporarily close a window to reduce clutter or free resources, but plan to return to the work later.\n\n`[name]`\n\n: Optional worktree name (the directory name). Defaults to current directory if omitted.\n\n```\n# Close the window for a specific worktree\nworkmux close user-auth\n\n# Close the current worktree's window (run from within the worktree)\nworkmux close\n```\n\nTo reopen the window later, use [ workmux open](#workmux-open-name).\n\n**Tip**: You can also use tmux's native kill-window command (default:\n`prefix + &`\n\n) to close a worktree's window with the same effect.\n\nRestores worktree windows after a tmux or computer crash. Uses persisted agent\nstate files to detect which worktrees had active agents before the crash, then\nreopens them with `--continue`\n\nto resume agent conversations.\n\n`--dry-run`\n\n: Show what would be restored without doing it.\n\n```\n# See what would be restored after a crash\nworkmux resurrect --dry-run\n\n# Restore all worktrees that had agents running\nworkmux resurrect\n```\n\n- Reads agent state files from\n`~/.local/state/workmux/agents/`\n\n- Matches each state file's working directory to a git worktree in the current repo\n- Skips worktrees that are already open or no longer exist\n- Opens each matched worktree with\n`--continue`\n\nto resume the agent\n\nRe-applies file operations (copy and symlink from `files`\n\nconfig) to existing\nworktrees. Useful when you add new entries to the `files`\n\nconfig or a symlink\nwas accidentally deleted.\n\n`--all`\n\n: Sync all worktrees instead of just the current one.\n\n```\n# Sync files to the current worktree\nworkmux sync-files\n\n# Sync files to all worktrees\nworkmux sync-files --all\n```\n\nPrints the filesystem path of an existing worktree. Useful for scripting or quickly navigating to a worktree directory.\n\n`<name>`\n\n: Worktree name (the directory name).\n\n```\n# Get the path of a worktree\nworkmux path user-auth\n# Output: /Users/you/project__worktrees/user-auth\n\n# Use in scripts or with cd\ncd \"$(workmux path user-auth)\"\n\n# Copy a file to a worktree\ncp config.json \"$(workmux path feature-branch)/\"\n```\n\nOpens a TUI dashboard showing all active AI agents across all tmux sessions. Useful for monitoring multiple parallel agents and quickly jumping between them.\n\n`-d, --diff`\n\n: Open the diff view directly for the current worktree. Useful when you want to quickly review uncommitted changes without navigating through the agent list.`-P, --preview-size <10-90>`\n\n: Set preview pane size as percentage (larger = more preview, less table). Default: 60.`-s, --session`\n\n: Filter to only show agents in the current session. Useful for session-per-project workflows where each session maps to a different repository.`-t, --tab <agents|worktrees>`\n\n: Open directly on the specified tab.\n\nImportant\n\nThis feature requires [agent status tracking](#agent-status-tracking) to be\nconfigured. Without it, no agents will appear in the dashboard.\n\n| Key | Action |\n|---|---|\n`1` -`9` |\nQuick jump to agent (closes dashboard) |\n`Tab` |\nToggle between current and last agent |\n`d` |\nView diff (opens WIP view) |\n`o` |\nOpen PR in browser |\n`p` |\nPeek at agent (dashboard stays open) |\n`s` |\nCycle sort mode |\n`/` |\nFilter agents by name |\n`F` |\nToggle session filter |\n`f` |\nToggle stale filter (show/hide stale) |\n`i` |\nEnter input mode (type to agent) |\n`Ctrl+u` |\nScroll preview up |\n`Ctrl+d` |\nScroll preview down |\n`+` /`-` |\nResize preview pane |\n`Enter` |\nGo to selected agent (closes dashboard) |\n`j` /`k` |\nNavigate up/down |\n`:` |\nOpen command palette |\n`q` /`Esc` |\nQuit |\n\nThe bottom half shows a live preview of the selected agent's terminal output.\nThe preview auto-scrolls to show the latest output, but you can scroll through\nhistory with `Ctrl+u`\n\n/`Ctrl+d`\n\n. Press `i`\n\nto enter input mode and type directly\nto the agent without leaving the dashboard.\n\n**#**: Quick jump key (1-9)** Project**: Project name (from`__worktrees`\n\npath or directory name)**Agent**: Worktree/window name** Git**: Diff stats showing branch changes (dim) and uncommitted changes (bright). Shows a rebase icon when a rebase is in progress.**Status**: Agent status icon (🤖 working, 💬 waiting, ✅ done, or \"stale\")** Time**: Time since last status change** Title**: Claude Code session title (auto-generated summary)\n\nPress `s`\n\nto cycle through sort modes:\n\n**Priority**(default): Waiting > Done > Working > Stale** Project**: Group by project name, then by priority within each project** Recency**: Most recently updated first** Natural**: Original tmux order (by pane creation)\n\nYour sort preference persists in the tmux session.\n\nPress `F`\n\nto toggle the session filter. When active, only agents in the current\nsession are shown. This is useful for session-per-project workflows where each\nsession maps to a repository. You can also start the dashboard with `--session`\n\nto default to session filtering. The preference persists across sessions.\n\nPress `/`\n\nto activate the name filter. Type to filter the agent list by project\nor worktree name (case-insensitive). Press `Enter`\n\nto accept the filter and\nreturn to normal navigation, or `Esc`\n\nto clear the filter. When a filter is\nactive, it is shown in the footer bar.\n\nPress `f`\n\nto toggle between showing all agents or hiding stale ones. The filter\nstate persists across dashboard sessions within the same tmux server.\n\nPress `d`\n\nto view the diff for the selected agent. The diff view has two modes:\n\n**WIP**- Shows uncommitted changes (`git diff HEAD`\n\n)**review**- Shows all changes on the branch vs main (`git diff main...HEAD`\n\n)\n\nPress `Tab`\n\nto toggle between modes. The footer displays which mode is active\nalong with diff statistics showing lines added (+) and removed (-).\n\n| Key | Action |\n|---|---|\n`Tab` |\nToggle WIP / review |\n`a` |\nEnter patch mode (WIP only) |\n`j` /`k` |\nScroll down/up |\n`Ctrl+d` |\nPage down |\n`Ctrl+u` |\nPage up |\n`c` |\nSend commit command to agent |\n`m` |\nTrigger merge and exit dashboard |\n`:` |\nOpen command palette |\n`q` /`Esc` |\nClose diff view |\n\nPatch mode (`a`\n\nfrom WIP diff) allows staging individual hunks like\n`git add -p`\n\n. This is useful for selectively staging parts of an agent's work.\n\nWhen [delta](https://github.com/dandavison/delta) is installed, hunks are\nrendered with syntax highlighting for better readability.\n\n| Key | Action |\n|---|---|\n`y` |\nStage current hunk |\n`n` |\nSkip current hunk |\n`u` |\nUndo last staged hunk |\n`s` |\nSplit hunk (if splittable) |\n`o` |\nComment on hunk (sends to agent) |\n`j` /`k` |\nNavigate to next/previous hunk |\n`:` |\nOpen command palette |\n`q` /`Esc` |\nExit patch mode |\n\nPress `y`\n\nto stage the current hunk and advance to the next. Press `n`\n\nto skip\nwithout staging. The counter in the header shows your progress (e.g., `[3/10]`\n\n).\n\nPress `s`\n\nto split the current hunk into smaller pieces when there are context\nlines between separate changes. Press `u`\n\nto undo the last staged hunk.\n\nPress `o`\n\nto comment on the current hunk. This sends a message to the agent\nincluding the file path, line number, the diff hunk as context, and your\ncomment. Useful for giving feedback like \"This function should handle the error\ncase\".\n\nAdd to your `~/.tmux.conf`\n\nfor quick access:\n\n```\nbind C-s display-popup -h 30 -w 100 -E \"workmux dashboard\"\n\n# Open directly on Worktrees tab\nbind C-w display-popup -h 30 -w 100 -E \"workmux dashboard --tab worktrees\"\n```\n\nThen press `prefix + Ctrl-s`\n\nto open the dashboard as a tmux popup.\n\nToggles a live agent status sidebar on the left or top edge of all tmux\nwindows. By default, each sidebar pane shows active agents across all tmux\nsessions with live status updates, providing an always-visible overview without\ntaking over the full screen like the dashboard. Use `workmux sidebar filter session`\n\nto show only agents in the current tmux session.\n\n```\nworkmux sidebar                 # Toggle sidebar on/off (all sessions)\nworkmux sidebar --session       # Toggle current session only, or opt out of global mode\nworkmux sidebar --position top  # Override configured placement for this toggle\n```\n\nThe sidebar displays:\n\n- Status icon (working/waiting/done with spinner animation)\n- Project and worktree name (e.g.\n`myproject/fix-bug`\n\n) - Elapsed time since last status change\n\n| Key | Action |\n|---|---|\n`j` /`k` |\nNavigate up/down |\n`Enter` |\nJump to agent |\n`g` /`G` |\nJump to first/last |\n`v` |\nToggle layout mode |\n`f` |\nToggle session filter |\n`q` |\nQuit sidebar |\n\nWith tmux mouse mode enabled (`set -g mouse on`\n\n), click an agent row or top-bar\nchip to jump to its pane, or scroll to navigate the list.\n\nWhen the global sidebar is active, `workmux sidebar --session`\n\nhides it in the\ncurrent tmux session only. Run the same command again to show it in that session\nagain while keeping the global sidebar active elsewhere.\n\nConfigure placement, width, and layout in `.workmux.yaml`\n\n:\n\n```\nsidebar:\n  position: left # \"left\" (default) or \"top\"\n  width: 40 # left width in columns, or \"15%\" for percentage\n  layout: tiles # left only: \"compact\" or \"tiles\" (default)\n```\n\nThe left sidebar defaults to 10% of terminal width, clamped between 25 and 50 columns. Widths above 80 columns use the default width so tmux pane expansion recovers automatically.\n\nUse `workmux sidebar --position top`\n\nor `--position left`\n\nto override the\nconfigured placement when enabling the sidebar.\n\n```\nbind C-t run-shell \"workmux sidebar\"\n```\n\nThen press `prefix + Ctrl-t`\n\nto toggle the sidebar.\n\nNote:The sidebar is currently tmux-only. When enabled, a sidebar pane is created in every existing window, and new windows automatically get one via a tmux hook.\n\nShows tracked agent processes whose last state update is older than a threshold. By default this is a dry run, though it still reconciles workmux state while checking live panes.\n\n```\nworkmux reap-agents\nworkmux reap-agents --hours 48\nworkmux reap-agents --hours 24 --force\n```\n\nUse `--force`\n\nto interrupt matching agents and remove their workmux agent state\nafter they exit.\n\nCommands for managing sandbox functionality. See the\n[sandbox guide](https://workmux.raine.dev/guide/sandbox/) for full\ndocumentation.\n\n| Command | Description |\n|---|---|\n`sandbox pull` |\nPull the latest container image from the registry |\n`sandbox build` |\nBuild the container image locally |\n`sandbox shell` |\nStart an interactive shell inside a sandbox |\n`sandbox agent` |\nRun the configured agent in a sandbox with RPC support |\n`sandbox stop` |\nStop running Lima VMs |\n`sandbox prune` |\nDelete unused Lima VMs to reclaim disk space |\n`sandbox install-dev` |\nCross-compile and install workmux into sandboxes (dev) |\n\nRemoves stale entries from Claude config (`~/.claude.json`\n\n) that point to\ndeleted worktree directories. When you run Claude Code in worktrees, it stores\nper-worktree settings in that file. Over time, as worktrees are merged or\ndeleted, it can accumulate entries for paths that no longer exist.\n\n- Scans\n`~/.claude.json`\n\nfor entries pointing to non-existent directories - Creates a backup at\n`~/.claude.json.bak`\n\nbefore making changes - Removes all stale entries\n- Reports the number of entries cleaned up\n\n- Only removes entries for absolute paths that don't exist\n- Creates a backup before modifying the file\n- Preserves all valid entries and relative paths\n\n```\n# Clean up stale Claude Code entries\nworkmux claude prune\n- Removing: /Users/user/project__worktrees/old-feature\n\n✓ Created backup at ~/.claude.json.bak\n✓ Removed 3 stale entries from ~/.claude.json\n```\n\nGenerates shell completion script for the specified shell. Completions provide tab-completion for commands and dynamic branch name suggestions.\n\n`<shell>`\n\n: Shell type:`bash`\n\n,`zsh`\n\n, or`fish`\n\n.\n\n```\n# Generate completions for zsh\nworkmux completions zsh\n```\n\nSee the [Shell Completions](#shell-completions) section for installation\ninstructions.\n\nDisplays this README with terminal formatting. Useful for quick reference without leaving the terminal.\n\nWhen run interactively, renders markdown with colors and uses a pager (`less`\n\n).\nWhen piped (e.g., to an LLM), outputs raw markdown for clean context.\n\nYou can ask an agent to read the docs and configure workmux for you:\n\n```\n> run `workmux docs` and configure workmux so that on the left pane\n  there is claude as agent, and on the right side neovim and empty\n  shell on top of each other\n\n⏺ Bash(workmux docs)\n  ⎿  <p align=\"center\">\n       <picture>\n     … +923 lines\n\n⏺ Write(.workmux.yaml)\n  ⎿  Wrote 9 lines to .workmux.yaml\n\n⏺ Created .workmux.yaml with the layout:\n  - Left: claude agent (focused)\n  - Right top: neovim\n  - Right bottom: empty shell\n```\n\nWorkmux can display the status of the agent in your tmux window list, giving you at-a-glance visibility into what the agent in each window doing.\n\n- 🤖 = agent is working\n- 💬 = agent is waiting for user input\n- ✅ = agent finished (auto-clears on window focus)\n\n| Agent | Status |\n|---|---|\n| Claude Code | ✅ Supported |\n| OpenCode | ✅ Supported |\n| Codex | ✅ Supported* |\n| Copilot CLI | ✅ Supported* |\n| Pi | ✅ Supported* |\n| Oh My Pi | ✅ Supported |\n| Gemini CLI | ✅ Supported |\n| Kiro |\n|\n\n[Tracking issue](https://github.com/mistralai/mistral-vibe/discussions/334)**Notes:**\n\n**Codex**: No 💬 waiting state** Copilot CLI**: No 💬 waiting state** Pi**: No 💬 waiting state** Kiro**: Hooks support is messy: requires a custom agent since the default can't be edited\n\nRun `workmux setup`\n\nto automatically detect Claude Code, Copilot CLI, OpenCode,\nPi, Oh My Pi, and other supported agent CLIs, install status tracking hooks, and install skills:\n\n```\nworkmux setup\n```\n\nYou can also run specific parts: `workmux setup --hooks`\n\nor\n`workmux setup --skills`\n\n. For Claude Code, `CLAUDE_CONFIG_DIR`\n\nis respected for\nboth hook and skill installation.\n\nWorkmux will also prompt you on first run if it detects an agent without status tracking or skills configured.\n\nWorkmux automatically modifies your tmux `window-status-format`\n\nto display the\nstatus icons. This happens once per session and only affects the current tmux\nsession (not your global config).\n\nIf you prefer manual setup:\n\n**Claude Code**: install the workmux status plugin:\n\n```\nclaude plugin marketplace add raine/workmux\nclaude plugin install workmux-status\n```\n\nOr manually add the hooks to `~/.claude/settings.json`\n\n. See\n[.claude-plugin/plugin.json](/raine/workmux/blob/main/.claude-plugin/plugin.json) for the hook\nconfiguration.\n\n**Copilot CLI**: copy the hooks to your repository:\n\n```\nmkdir -p .github/hooks/workmux-status\ncurl -o .github/hooks/workmux-status/hooks.json \\\n  https://raw.githubusercontent.com/raine/workmux/main/.github/hooks/workmux-status/hooks.json\n```\n\nNote: Copilot hooks are per-repository. The waiting state is not supported due to limitations in the Copilot CLI hooks implementation.\n\n**OpenCode**: download the workmux status plugin:\n\n```\nmkdir -p ~/.config/opencode/plugins\ncurl -o ~/.config/opencode/package.json \\\n  https://raw.githubusercontent.com/raine/workmux/main/resources/opencode/package.json\ncurl -o ~/.config/opencode/plugins/workmux-status.ts \\\n  https://raw.githubusercontent.com/raine/workmux/main/resources/opencode/plugins/workmux-status.ts\n```\n\nRestart OpenCode for the plugin to take effect.\n\n**Oh My Pi**: copy the workmux status extension to your global OMP extensions directory:\n\n```\nmkdir -p ~/.omp/agent/extensions\ncurl -o ~/.omp/agent/extensions/workmux-status.ts \\\n  https://raw.githubusercontent.com/raine/workmux/main/.omp/extensions/workmux-status.ts\n```\n\nRestart omp for the extension to take effect.\n\nYou can customize the icons in your config:\n\n```\n# ~/.config/workmux/config.yaml\nstatus_icons:\n  working: '🔄'\n  waiting: '⏸️'\n  done: '✔️'\n```\n\nIf you prefer to manage the tmux format yourself, disable auto-modification and\nadd the status variable to your `~/.tmux.conf`\n\n:\n\n```\n# ~/.config/workmux/config.yaml\nstatus_format: false\n# ~/.tmux.conf\nset -g window-status-format '#I:#W#{?@workmux_status, #{@workmux_status},}#{?window_flags,#{window_flags}, }'\nset -g window-status-current-format '#I:#W#{?@workmux_status, #{@workmux_status},}#{?window_flags,#{window_flags}, }'\n```\n\nUse `workmux last-done`\n\nto quickly switch to the agent that most recently\nfinished its task or is waiting for user input. Repeated invocations cycle\nthrough all completed and waiting agents in reverse chronological order.\n\nAdd a tmux keybinding for quick access:\n\n```\n# ~/.tmux.conf\nbind-key L run-shell \"workmux last-done\"\n```\n\nThen press `prefix + L`\n\nto jump to the last completed or waiting agent, press\nagain to cycle to the next oldest, and so on.\n\nUse `workmux last-agent`\n\nto toggle between your current agent and the last one\nyou visited. This works like vim's `Ctrl+^`\n\nor tmux's `last-window`\n\n- it\nremembers which agent you came from and switches back to it. Pressing it again\nreturns you to where you were.\n\nThis is available both as a CLI command and as the `Tab`\n\nkey in the dashboard.\n\nAdd a tmux keybinding for quick access:\n\n```\n# ~/.tmux.conf\nbind Tab run-shell \"workmux last-agent\"\n```\n\nThen press `prefix + Tab`\n\nto toggle between your two most recent agents.\n\nworkmux can run agents inside containers (Docker/Podman/Apple Container) or Lima\nVMs, isolating them from your host. Agents are restricted to the project\nworktree; sensitive files like SSH keys, AWS credentials, and other secrets are\nnot accessible. This lets you run agents with `--dangerously-skip-permissions`\n\nwithout worrying about what they might touch on your host.\n\nSandboxing is transparent: status indicators, the dashboard, spawning new agents, and merging all continue to work normally across the sandbox boundary.\n\n| Container (Docker/Podman/Apple Container) | Lima VM | |\n|---|---|---|\nIsolation |\nProcess/VM-level | Machine-level (virtual machine) |\nPersistence |\nEphemeral (new container per session) | Persistent (stateful VMs) |\nToolchain |\nCustom Dockerfile or host command proxying | Built-in Nix & Devbox support |\nNetwork |\nOptional restrictions (domain allowlist) | Unrestricted |\n\nContainer is a good default: simple to set up and ephemeral, so no state accumulates between sessions. Choose Lima if you want persistent VMs with built-in Nix/Devbox toolchain support.\n\n```\n# ~/.config/workmux/config.yaml or .workmux.yaml\nsandbox:\n  enabled: true\n  # backend: lima  # uncomment for Lima VMs (default: container)\n```\n\nThe pre-built container image is pulled automatically on first run. For Lima, the VM is created and provisioned on first use.\n\nBoth backends support:\n\n**Host command proxying**: Run specific commands (build tools, linters) on the host from inside the sandbox via`host_commands`\n\nconfig**Extra mounts**: Mount additional host directories into the sandbox (read-only by default)** Git identity**: Your`user.name`\n\nand`user.email`\n\nare automatically injected so git commits work without exposing your full`~/.gitconfig`\n\n**Credential sharing**: Agent credentials are shared between host and sandbox** Network restrictions**(container only): Block outbound connections except to approved domains\n\nSee the [sandbox guide](https://workmux.raine.dev/guide/sandbox/) for full\nsetup, configuration, and security details.\n\nBy default, workmux creates tmux **windows** within your current session. With\nsession mode, each worktree gets its own **tmux session** instead. This allows\neach worktree to have multiple windows.\n\nAdd to your config:\n\n```\n# ~/.config/workmux/config.yaml or .workmux.yaml\nmode: session\n```\n\nOr use the `--session`\n\nflag:\n\n```\nworkmux add feature-branch --session\n```\n\n**Persistence**: The mode is stored per-worktree. If you create a worktree with`--session`\n\n, subsequent`open`\n\n/`close`\n\n/`remove`\n\ncommands automatically use session mode for that worktree.**Navigation**: After`merge`\n\nor`remove`\n\n, workmux switches you back to the previous session.\n\nUse the `windows`\n\nconfig to launch multiple windows in each session. Each window\ncan have its own pane layout. This is mutually exclusive with the top-level\n`panes`\n\nconfig.\n\n```\nmode: session\nwindows:\n  - name: editor\n    panes:\n      - command: <agent>\n        focus: true\n      - split: horizontal\n        size: 20\n  - name: tests\n    panes:\n      - command: just test --watch\n  - panes:\n      - command: tail -f app.log\n```\n\nEach window supports:\n\n| Option | Description | Default |\n|---|---|---|\n`name` |\nWindow name (if omitted, tmux auto-names from command) | Auto |\n`panes` |\nPane layout (same syntax as top-level `panes` ) |\nSingle shell |\n\n`focus: true`\n\nworks across windows: the last pane with focus set determines\nwhich window is selected when the session opens.\n\n**tmux only**: Session mode is currently only supported for the tmux backend.** No duplicates**: Unlike window mode which supports opening multiple windows for the same worktree (`-2`\n\n,`-3`\n\nsuffixes), session mode creates one session per worktree.\n\nHere's a complete workflow:\n\n```\n# Start a new feature\nworkmux add user-auth\n\n# Work on your feature...\n# (tmux automatically sets up your configured panes and environment)\n\n# When ready, merge and clean up\nworkmux merge user-auth\n\n# Start another feature\nworkmux add api-endpoint\n\n# List all active worktrees\nworkmux list\n```\n\nworkmux turns a multi-step manual workflow into simple commands, making parallel development workflows practical.\n\n```\n# 1. Manually create the worktree and environment\ngit worktree add ../worktrees/user-auth -b user-auth\ncd ../worktrees/user-auth\ncp ../../project/.env.example .env\nln -s ../../project/node_modules .\nnpm install\n# ... and other setup steps\n\n# 2. Manually create and configure the tmux window\ntmux new-window -n user-auth\ntmux split-window -h 'npm run dev'\ntmux send-keys -t 0 'claude' C-m\n# ... repeat for every pane in your desired layout\n\n# 3. When done, manually merge and clean everything up\ncd ../../project\ngit switch main && git pull\ngit merge --no-ff user-auth\ntmux kill-window -t user-auth\ngit worktree remove ../worktrees/user-auth\ngit branch -d user-auth\n# Create the environment\nworkmux add user-auth\n\n# ... work on the feature ...\n\n# Merge and clean up\nworkmux merge\n```\n\nRun multiple AI agents simultaneously, each in its own worktree.\n\n```\n# Spin up two agents working on different tasks\nworkmux add refactor-user-model -p \"Refactor the User model to use composition\"\nworkmux add add-search-endpoint -p \"Add a /search endpoint with pagination\"\n\n# Each agent works in isolation. Check progress via tmux windows or the dashboard\nworkmux dashboard\n\n# Merge completed work back to main\nworkmux merge refactor-user-model\nworkmux merge add-search-endpoint\n```\n\nTip\n\nUse `-A`\n\n(`--auto-name`\n\n) to generate branch names automatically from your\nprompt, so you don't have to think of one. See\n[Automatic branch name generation](#automatic-branch-name-generation).\n\n[Git worktrees](https://git-scm.com/docs/git-worktree) let you have multiple\nbranches checked out at once in the same repository, each in a separate\ndirectory. This provides two main advantages over a standard single-directory\nsetup:\n\n-\n**Painless context switching**: Switch between tasks just by changing directories (`cd ../other-branch`\n\n). There's no need to`git stash`\n\nor make temporary commits. Your work-in-progress, editor state, and command history remain isolated and intact for each branch. -\n**True parallel development**: Work on multiple branches simultaneously without interference. You can run builds, install dependencies (`npm install`\n\n), or run tests in one worktree while actively coding in another. This isolation is perfect for running multiple AI agents in parallel on different tasks.\n\nIn a standard Git setup, switching branches disrupts your flow by requiring a\nclean working tree. Worktrees remove this friction. `workmux`\n\nautomates the\nentire process and pairs each worktree with a dedicated tmux window, creating\nfully isolated development environments. See\n[Before and after](#before-and-after) for how workmux streamlines this workflow.\n\nWhile powerful, git worktrees have nuances that are important to understand. workmux is designed to automate solutions to these, but awareness of the underlying mechanics helps.\n\n[Gitignored files require configuration](#gitignored-files-require-configuration)[Conflicts](#conflicts)[Package manager considerations (pnpm, yarn)](#package-manager-considerations-pnpm-yarn)[Rust projects](#rust-projects)[Port conflicts in monorepos](#port-conflicts-in-monorepos)[Symlinks and](#symlinks-and-gitignore-trailing-slashes)`.gitignore`\n\ntrailing slashes\n\nWhen `git worktree add`\n\ncreates a new working directory, it's a clean checkout.\nFiles listed in your `.gitignore`\n\n(e.g., `.env`\n\nfiles, `node_modules`\n\n, IDE\nconfiguration) will not exist in the new worktree by default. Your application\nwill be broken in the new worktree until you manually create or link these\nnecessary files.\n\nThis is a primary feature of workmux. Use the `files`\n\nsection in your\n`.workmux.yaml`\n\nto automatically copy or symlink these files on creation:\n\n```\n# .workmux.yaml\nfiles:\n  copy:\n    - .env # Copy environment variables\n  symlink:\n    - .next/cache # Share Next.js build cache\n```\n\nNote: Symlinking `node_modules`\n\ncan be efficient but only works if all worktrees\nshare identical dependencies. If different branches have different dependency\nversions, each worktree needs its own installation. For dependency installation,\nconsider using a pane command instead of `post_create`\n\nhooks - this runs the\ninstall in the background without blocking the worktree and window creation:\n\n```\npanes:\n  - command: npm install\n    focus: true\n  - split: horizontal\n```\n\nWorktrees isolate your filesystem, but they do not prevent merge conflicts. If you modify the area of code on two different branches (in two different worktrees), you will still have a conflict when you merge one into the other.\n\nThe best practice is to work on logically separate features in parallel worktrees. When conflicts are unavoidable, use standard git tools to resolve them. You can also leverage an AI agent within the worktree to assist with the conflict resolution.\n\nModern package managers like `pnpm`\n\nuse a global store with symlinks to\n`node_modules`\n\n. Each worktree typically needs its own `pnpm install`\n\nto set up\nthe correct dependency versions for that branch.\n\nIf your worktrees always have identical dependencies (e.g., working on multiple\nfeatures from the same base), you could potentially symlink `node_modules`\n\nbetween worktrees. However, this breaks as soon as branches diverge in their\ndependencies, so it's generally safer to run a fresh install in each worktree.\n\nNote: In large monorepos, cleaning up `node_modules`\n\nduring worktree removal can\ntake significant time. workmux has a\n[special cleanup mechanism](https://github.com/raine/workmux/blob/main/src/scripts/cleanup_node_modules.sh)\nthat moves `node_modules`\n\nto a temporary location and deletes it in the\nbackground, making the `remove`\n\ncommand return almost instantly.\n\nUnlike `node_modules`\n\n, Rust's `target/`\n\ndirectory should **not** be symlinked\nbetween worktrees. Cargo locks the `target`\n\ndirectory during builds, so sharing\nit would block parallel builds and defeat the purpose of worktrees.\n\nInstead, use [sccache](https://github.com/mozilla/sccache) to share compiled\ndependencies across worktrees:\n\n```\nbrew install sccache\n```\n\nAdd to `~/.cargo/config.toml`\n\n:\n\n```\n[build]\nrustc-wrapper = \"sccache\"\n```\n\nThis caches compiled dependencies globally, so new worktrees benefit from cached artifacts without any lock contention.\n\nWhen running multiple services (API, web app, database) in a monorepo, each\nworktree needs unique ports to avoid conflicts. For example, if your `.env`\n\nhas\nhardcoded ports like `API_PORT=3001`\n\nand `VITE_PORT=3000`\n\n, running two worktrees\nsimultaneously would fail because both would try to bind to the same ports.\nSimply copying `.env`\n\nfiles won't work since all worktrees would use the same\nports.\n\n**Solution**: Use a `post_create`\n\nhook to generate a `.env.local`\n\nfile with\nunique ports. Many frameworks (Vite, Next.js, CRA) automatically load\n`.env.local`\n\nand merge it with `.env`\n\n, with `.env.local`\n\ntaking precedence. For\nplain Node.js, use multiple `--env-file`\n\nflags where later files override\nearlier ones.\n\nCreate a script at `scripts/worktree-env`\n\n:\n\n``` bash\n#!/usr/bin/env bash\nset -euo pipefail\n\nport_in_use() {\n  lsof -nP -iTCP:\"$1\" -sTCP:LISTEN &>/dev/null\n}\n\nfind_port() {\n  local port=$1\n  while port_in_use \"$port\"; do\n    ((port++))\n  done\n  echo \"$port\"\n}\n\n# Hash the handle to get a deterministic port offset (0-99)\nhash=$(echo -n \"$WM_HANDLE\" | md5 | cut -c1-4)\noffset=$((16#$hash % 100))\n\n# Find available ports starting from the hash-based offset\napi_port=$(find_port $((3001 + offset * 10)))\nvite_port=$(find_port $((3000 + offset * 10)))\n\n# Generate .env.local with port overrides\ncat >.env.local <<EOF\nAPI_PORT=$api_port\nVITE_PORT=$vite_port\nVITE_PUBLIC_API_URL=http://localhost:$api_port\nEOF\n\necho \"Created .env.local with ports: API=$api_port, VITE=$vite_port\"\n```\n\nConfigure workmux to copy `.env`\n\nand generate `.env.local`\n\n:\n\n```\n# .workmux.yaml\nfiles:\n  copy:\n    - .env # Copy secrets (DATABASE_URL, API keys, etc.)\n\npost_create:\n  - ./scripts/worktree-env # Generate .env.local with unique ports\n```\n\nFor plain Node.js (without framework support), load both files with later overriding earlier:\n\n```\n{\n  \"scripts\": {\n    \"api\": \"node --env-file=.env --env-file=.env.local api/server.js\",\n    \"web\": \"node --env-file=.env --env-file=.env.local web/server.js\"\n  }\n}\n```\n\nEach worktree now gets unique ports derived from its name, allowing multiple\ninstances to run simultaneously without conflicts. The `.env`\n\nfile stays\nuntouched, and `.env.local`\n\nis gitignored.\n\nSee the [Monorepos guide](https://workmux.raine.dev/guide/monorepos) for\nalternative approaches using direnv.\n\nIf your `.gitignore`\n\nuses a trailing slash to ignore directories (e.g.,\n`tests/venv/`\n\n), symlinks to that path in the created worktree will **not** be\nignored and will show up in `git status`\n\n. This is because `venv/`\n\nonly matches\ndirectories, not files (symlinks).\n\nTo ignore both directories and symlinks, remove the trailing slash:\n\n```\n- tests/venv/\n+ tests/venv\n```\n\nOn first run, workmux prompts you to check if a git branch icon displays\ncorrectly. If you have a [Nerd Font](https://www.nerdfonts.com/) installed,\nanswer yes to enable nerdfont icons throughout the interface, including the tmux\nwindow prefix.\n\nTo change the setting later, edit `~/.config/workmux/config.yaml`\n\n:\n\n```\nnerdfont: true # or false for unicode fallbacks\n```\n\nIf your project uses [direnv](https://direnv.net/) for environment management,\nyou can configure workmux to automatically set it up in new worktrees:\n\n```\n# .workmux.yaml\npost_create:\n  - direnv allow\n\nfiles:\n  symlink:\n    - .envrc\n```\n\nBy default, Claude Code prompts for permission before running commands. There are several ways to handle this in worktrees:\n\n**Share permissions across worktrees**\n\nTo keep permission prompts but share granted permissions across worktrees:\n\n```\nfiles:\n  symlink:\n    - .claude/settings.local.json\n```\n\nAdd this to your global config (`~/.config/workmux/config.yaml`\n\n) or project's\n`.workmux.yaml`\n\n. Since this file contains user-specific permissions, also add it\nto `.gitignore`\n\n:\n\n```\n.claude/settings.local.json\n```\n\n**Named agent profiles**\n\nDefine [named agents](https://workmux.raine.dev/guide/agents#named-agents) in\nyour global config when an agent needs a wrapper command, extra arguments, or\nenvironment variables. Simple string aliases still work:\n\n```\n# ~/.config/workmux/config.yaml\nagents:\n  cc-work: \"claude\"\n  cc-personal: \"env CLAUDE_CONFIG_DIR=~/.claude-personal claude\"\n  cc-bedrock: \"env -u CLAUDE_CODE_USE_BEDROCK -u AWS_REGION AWS_PROFILE=prod claude\"\n  cc-yolo: \"claude --dangerously-skip-permissions\"\n  cod: \"codex --yolo\"\n```\n\nStructured profiles make the same kind of config easier to maintain because arguments and environment are not written as one long shell string:\n\n```\n# ~/.config/workmux/config.yaml\nagents:\n  cc-personal:\n    type: claude\n    command: claude\n    env:\n      CLAUDE_CONFIG_DIR: ~/.claude-personal\n      ANTHROPIC_AUTH_TOKEN:\n        from_env: ANTHROPIC_AUTH_TOKEN\n  cod-mini:\n    type: codex\n    command: codex\n    args:\n      - exec\n      - -m\n      - gpt-5.1-codex-mini\n```\n\nTo skip prompts entirely, define a named agent with the Claude skip-permissions flag:\n\n```\n# ~/.config/workmux/config.yaml\nagents:\n  cc-yolo:\n    type: claude\n    command: claude\n    args:\n      - --dangerously-skip-permissions\n```\n\nReference a named profile per project with `agent: cc-yolo`\n\n, pass it with\n`-a cc-yolo`\n\n, or use it directly in a pane with `<agent:cc-yolo>`\n\n. Structured\nprofiles support `command`\n\n, `args`\n\n, `env`\n\n, and `type`\n\nfields.\n\nThe `/worktree`\n\n[skill](https://workmux.raine.dev/guide/skills) lets you\ndelegate tasks to parallel worktree agents directly from your conversation. A\nmain agent on the main branch can act as a coordinator: planning work and\nspinning up worktree agents for each task.\n\n📝 **See\nthis blog post** for a\ndetailed walkthrough of the workflow.\n\n```\n> /worktree Implement user authentication\n> /worktree Fix the race condition in handler.go\n> /worktree Add dark mode, Implement caching  # multiple tasks\n```\n\nSee the [Skills guide](https://workmux.raine.dev/guide/skills) for more skills\nincluding `/merge`\n\n, `/rebase`\n\n, `/coordinator`\n\n, and `/open-pr`\n\n.\n\nTo enable tab completions for commands and branch names, add the following to your shell's configuration file.\n\nFor **bash**, add to your `.bashrc`\n\n:\n\n```\neval \"$(workmux completions bash)\"\n```\n\nFor **zsh**, add to your `.zshrc`\n\n:\n\n```\neval \"$(workmux completions zsh)\"\n```\n\nFor **fish**, add to your `config.fish`\n\n:\n\n```\nworkmux completions fish | source\n```\n\n- Rust (for building)\n- Git 2.5+ (for worktree support)\n- tmux (or an alternative backend)\n\nWhile tmux is the primary and recommended backend, workmux also supports alternative terminal multiplexers:\n\n(experimental) - For users who prefer WezTerm's features. Thanks to[WezTerm](https://workmux.raine.dev/guide/wezterm)[@JeremyBYU](https://github.com/JeremyBYU)for contributing this backend.(experimental) - For users who prefer kitty terminal. Requires[kitty](https://workmux.raine.dev/guide/kitty)`allow_remote_control`\n\nand`listen_on`\n\nconfiguration.(experimental) - For users who prefer Zellij. Detected automatically via[Zellij](https://workmux.raine.dev/guide/zellij)`$ZELLIJ`\n\n.\n\nworkmux auto-detects the backend from environment variables (`$TMUX`\n\n,\n`$WEZTERM_PANE`\n\n, `$KITTY_WINDOW_ID`\n\n, or `$ZELLIJ`\n\n). Session-specific variables\nare checked first, so running tmux inside kitty correctly selects the tmux\nbackend. Set `$WORKMUX_BACKEND`\n\nto override detection.\n\nworkmux is inspired by [wtp](https://github.com/satococoa/wtp), an excellent git\nworktree management tool. While wtp streamlines worktree creation and setup,\nworkmux takes this further by tightly coupling worktrees with tmux window\nmanagement.\n\nFor managing multiple AI agents in parallel, tools like\n[claude-squad](https://github.com/smtg-ai/claude-squad) and\n[vibe-kanban](https://github.com/BloopAI/vibe-kanban/) offer dedicated\ninterfaces, like a TUI or kanban board. In contrast, workmux adheres to its\nphilosophy that **tmux is the interface**, providing a native tmux experience\nfor managing parallel workflows without requiring a separate interface to learn.\n\nBug reports and feature suggestions are always welcome via issues or discussions. Large and/or complex PRs, especially without prior discussion, may not get merged. Thanks for contributing!\n\nSee [CONTRIBUTING.md](/raine/workmux/blob/main/CONTRIBUTING.md) for development setup.\n\n[tmux-tools](https://github.com/raine/tmux-tools)— Collection of tmux utilities including file picker, smart sessions, and more[tmux-file-picker](https://github.com/raine/tmux-file-picker)— Pop up fzf in tmux to quickly insert file paths, perfect for AI coding assistants[tmux-bro](https://github.com/raine/tmux-bro)— Smart tmux session manager that sets up project-specific sessions automatically[git-surgeon](https://github.com/raine/git-surgeon)— Non-interactive hunk-level git staging for AI agents[claude-history](https://github.com/raine/claude-history)— Search and view Claude Code conversation history with fzf[consult-llm](https://github.com/raine/consult-llm)— Consult other AI models from your agent workflow[tmux-agent-usage](https://github.com/raine/tmux-agent-usage)— Display AI agent rate limit usage in your tmux status bar", "url": "https://wpnews.pro/news/parallel-development-in-tmux-with-git-worktrees", "canonical_source": "https://github.com/raine/workmux", "published_at": "2026-07-07 20:42:57+00:00", "updated_at": "2026-07-07 20:59:52.151774+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Raine", "workmux", "tmux", "git", "kitty", "WezTerm", "Zellij", "aven"], "alternates": {"html": "https://wpnews.pro/news/parallel-development-in-tmux-with-git-worktrees", "markdown": "https://wpnews.pro/news/parallel-development-in-tmux-with-git-worktrees.md", "text": "https://wpnews.pro/news/parallel-development-in-tmux-with-git-worktrees.txt", "jsonld": "https://wpnews.pro/news/parallel-development-in-tmux-with-git-worktrees.jsonld"}}