Parallel development in tmux* with Git worktrees

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.

Parallel development in tmux with git worktrees 📖 Documentation https://workmux.raine.dev/ · Install installation · Quick start quick-start · Commands commands · Changelog /raine/workmux/blob/main/CHANGELOG.md 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. Tip I'm building aven https://github.com/raine/aven , a local-first task manager for power users and agents who live in the terminal. 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 - 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.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 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 Automatic branch name generation automatic-branch-name-generation from prompts using LLM- Shell completions "I've been using and loving workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow." — @Coolin96 🔗 "Thank you so much for your work with workmux It's a tool I've been wanting to exist for a long time." — @rstacruz 🔗 "It's become my daily driver - the perfect level of abstraction over tmux + git, without getting in the way or obscuring the underlying tooling." — @cisaacstern 🔗 "I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows." — @dedbrizz 🔗 curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash brew install raine/workmux/workmux Other methods Cargo, mise, Nix Cargo requires rustup https://rustup.rs/ : cargo install workmux mise: mise use -g cargo:raine/workmux Nix flake and home-manager setup https://workmux.raine.dev/guide/nix : nix profile install github:raine/workmux For manual installation, see pre-built binaries https://github.com/raine/workmux/releases/latest . 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. - Initialize configuration optional : workmux init This creates a .workmux.yaml file to customize your workflow pane layouts, setup commands, file operations, etc. . workmux works out of the box with sensible defaults, so this step is optional. - Create a new worktree and tmux window : workmux add new-feature This will: - Create a git worktree at <project root /../<project name worktrees/new-feature - Copy config files and symlink dependencies if configured file-operations - Run any setup commands post create - 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 - Create a git worktree at - Do your thing - 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. 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.raine.dev/guide/monorepos nested-configuration for details. For post create and file operation lists files.copy , files.symlink , you can use "<global " to include global values alongside project-specific ones. Other settings like panes are replaced entirely when defined in the project config. ~/.config/workmux/config.yaml : nerdfont: true Enable nerdfont icons prompted on first run merge strategy: rebase Make workmux merge do rebase by default merge keep: true Keep worktree, window, and branch after merge by default agent: claude panes: - command: <agent Start the configured agent e.g., claude focus: true - split: horizontal Second pane with default shell .workmux.yaml : post create: - '<global ' - mise use files: symlink: - '<global ' Include global symlinks node modules - .pnpm-store Add project-specific symlink panes: - command: pnpm install focus: true - command: <agent split: horizontal - command: pnpm run dev split: vertical For a real-world example, see workmux's own .workmux.yaml https://github.com/raine/workmux/blob/main/.workmux.yaml . Most options have sensible defaults. You only need to configure what you want to customize. | Option | Description | Default | |---|---|---| main branch | Branch to merge into | Auto-detected | base branch | Default base branch for new worktrees | Current branch | worktree dir | Directory for worktrees absolute or relative . Supports ~ and {project} . | <project worktrees/ | window prefix | Prefix for tmux window/session names | wm- | mode | Tmux mode window or session | window | window placement | New tmux window placement after current or rightmost | after current | agent | Default agent for <agent placeholder | claude | agents | Named agent commands | {} merge strategy merge , rebase , squash merge merge keep workmux merge by default false theme custom colors https://workmux.raine.dev/guide/configuration custom-colors default auto dark/light | 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 Define your tmux pane layout with the panes array. For multiple windows in session mode, use windows multiple-windows-per-session instead they are mutually exclusive . panes: - command: <agent focus: true - command: npm run dev split: horizontal size: 15 Each pane supports: | Option | Description | Default | |---|---|---| command | Command to run see | focus false zoom focus: true false split horizontal or vertical size percentage <agent : resolves to the configured agent from agent config or --agent flag Built-in agents claude , gemini , codex , opencode , kiro-cli , vibe , pi , omp are auto-detected when used as literal commands and receive prompt injection automatically, without needing the <agent placeholder or a matching agent config: panes: - command: 'claude --dangerously-skip-permissions' focus: true - command: 'codex --yolo' split: vertical Each agent receives the prompt via -p / -P / -e using the correct format for that agent. Auto-detection matches the executable name regardless of flags or path. Define reusable pane arrangements in the layouts map and select one at add-time with -l/--layout : layouts: design: panes: - command: <agent focus: true - command: <agent:codex split: vertical review: panes: - command: <agent workmux add my-feature -l design When -l is used, the layout's panes replace the top-level panes for that worktree. All other config hooks, files, agent, etc. comes from the top-level as usual. The -l flag cannot be combined with --agent . New worktrees are clean checkouts with no gitignored files .env , node modules , etc. . Use files to automatically copy or symlink what each worktree needs: files: copy: - .env symlink: - .next/cache Share build cache across worktrees Both copy and symlink accept glob patterns. To re-apply file operations to an existing worktree e.g., after updating the config , run workmux sync-files from inside the worktree. Use --all to sync all worktrees at once. 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.raine.dev/guide/monorepos nested-configuration and receive environment variables: WM HANDLE , WM WORKTREE PATH , WM PROJECT ROOT , WM CONFIG DIR . WM CONFIG DIR points to the directory containing the .workmux.yaml that was used, which may differ from WM WORKTREE PATH when using nested configs. | 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: post create: - direnv allow pre merge: - just check Customize the icons shown in tmux window names: 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 - Worktrees are created in <project 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 - For projects with a post create commands are optional and only run if you configure them 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. panes: Pane 1: Install dependencies, then start dev server - command: pnpm install && pnpm run dev Pane 2: AI agent - command: <agent split: horizontal focus: true 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} . For faster typing, alias workmux to wm : alias wm='workmux' - Create a new worktree and tmux window add - Merge a branch and clean up everything merge - Rebase a worktree branch onto its base branch rebase - Remove worktrees without merging remove - List all worktrees with status list - Open a tmux window for an existing worktree open - Close a worktree's tmux window keeps worktree close - Restore worktree windows after a crash resurrect - Get the filesystem path of a worktree path - Show TUI dashboard of all active agents dashboard - Toggle a compact agent status sidebar in tmux sidebar - Exit tracked agent processes older than a threshold reap-agents - Edit the global configuration file config edit - Generate configuration file init - Manage sandbox backends container/Lima sandbox - Clean up stale Claude Code entries claude prune - Generate shell completions completions - Show detailed documentation docs 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. <branch-name : 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 . --base <branch|commit|tag : Specify a base branch, commit, or tag to branch from when creating a new branch. Overrides base branch config. Defaults to base branch from config, then the currently checked out branch. --pr <number : Checkout a GitHub pull request by its number into a new worktree.- Requires the gh command-line tool to be installed and authenticated. - 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. - Requires the -A, --auto-name : Generate branch name from prompt using LLM. See Automatic branch name generation automatic-branch-name-generation . --name <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 . -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 <text : Provide an inline prompt that will be automatically passed to AI agent panes. -P, --prompt-file <path : 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 <name : Use a named pane layout from config instead of the default panes. Cannot be combined with --agent . -a, --agent <name : 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. --config <path : 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=<session-id to fork a specific session prefix matching supported . Currently supports Claude Code. 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 - 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. - Creates a git worktree at <worktree dir /<handle the worktree dir is configurable and defaults to a sibling directory of your project - Runs any configured file operations copy/symlink - Executes post create commands if defined runs before the tmux window opens, so keep them fast - Creates a new tmux window named <window prefix <handle e.g., wm-feature-auth with window prefix: wm- - Sets up your configured tmux pane layout - Automatically switches your tmux client to the new window 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 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 Checkout PR 123. The local branch will be named after the PR's branch. workmux add --pr 123 Checkout PR 456 with a custom local branch name workmux add fix/api-bug --pr 456 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 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 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 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 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 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 , opencode , gemini , kiro-cli , vibe , pi , omp , 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: "<agent " } 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-<branch .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 . The --auto-name -A flag generates a branch name from your prompt using an LLM. The tool used depends on your configuration: auto name.command is set: uses that command as-is config.agent is a known agent claude , gemini , codex , opencode , kiro-cli , vibe , pi , omp : uses the agent's CLI with a fast/cheap model- Neither: falls back to the CLI tool llm 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 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: pipx install llm Configure a model e.g., OpenAI : llm keys set openai Or use a local model llm install llm-ollama If you set auto name.command , llm is not required. When an agent is configured, these commands are used automatically: | Agent | Auto-name command | |---|---| claude | claude --model haiku -p | gemini | gemini -m gemini-2.5-flash-lite -p | codex | codex exec --config model reasoning effort="low" -m gpt-5.1-codex-mini | opencode | opencode run | kiro-cli | kiro-cli chat --no-interactive | pi | pi -p | omp | omp -p | To override back to llm when an agent is configured, set auto name.command: "llm" . Optionally configure auto-name behavior in .workmux.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. 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 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. -a, --agent <name : When used multiple times, creates one worktree for each agent. -n, --count <number : Creates <number worktree instances. Can be combined with a single --agent flag to apply that agent to all instances. --foreach <matrix : 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 <template : A MiniJinja https://docs.rs/minijinja/latest/minijinja/ Jinja2-compatible template for generating branch names.- Available variables: {{ base name }} , {{ agent }} , {{ num }} , {{ index }} , {{ input }} stdin , and any variables from --foreach . - Default: {{ base name }}{% if agent %}-{{ agent | slugify }}{% endif %}{% for key, value in foreach vars %}-{{ value | slugify }}{% endfor %}{% if num %}-{{ num }}{% endif %} - Available variables: --max-concurrent <number : Limits how many worktrees run simultaneously. When set, workmux creates up to <number worktrees, 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 . When generating multiple worktrees, any prompt provided via -p , -P , or -e is treated as a MiniJinja template. You can use variables from your generation mode to create unique prompts for each agent or instance. For ordinary single-worktree add commands, prompt text is not templated. Instead of passing --foreach on the command line, you can specify the variable matrix directly in your prompt file using YAML frontmatter. This is more convenient for complex matrices and keeps the variables close to the prompt that uses them. Format: Create a prompt file with YAML frontmatter at the top, separated by --- : Example 1: mobile-task.md --- foreach: platform: iOS, Android lang: swift, kotlin --- Build a {{ platform }} app using {{ lang }}. Implement user authentication and data persistence. workmux add mobile-app --prompt-file mobile-task.md Generates worktrees: mobile-app-ios-swift, mobile-app-android-kotlin Example 2: agent-task.md using agent as a foreach variable --- foreach: agent: claude, gemini --- Implement the dashboard refactor using your preferred approach. workmux add refactor --prompt-file agent-task.md Generates worktrees: refactor-claude, refactor-gemini Behavior: - Variables from the frontmatter are available in both the prompt template and the branch name template - All value lists must have the same length, and values are paired by index position same zip behavior as --foreach - CLI --foreach overrides frontmatter with a warning if both are present - Works with both --prompt-file and --prompt-editor You can pipe input lines to workmux add to create multiple worktrees. Each line becomes available as the {{ input }} template variable in your prompt. This is useful for batch-processing tasks from external sources. Plain text: Each line becomes {{ input }} echo -e "api\nauth\ndatabase" | workmux add refactor -P task.md {{ input }} = "api", "auth", "database" JSON lines: Each key becomes a template variable gh repo list --json url,name --jq -c '. ' | workmux add analyze \ --branch-template '{{ base name }}-{{ name }}' \ -P prompt.md Line: {"url":"https://github.com/raine/workmux","name":"workmux"} Variables: {{ url }}, {{ name }}, {{ input }} raw JSON line This lets you structure data upstream with jq and use meaningful branch names while keeping the full URL available in your prompt. Behavior: - Empty lines and whitespace-only lines are filtered out - Stdin input cannot be combined with --foreach mutually exclusive - JSON objects lines starting with { are parsed and each key becomes a variable {{ input }} always contains the raw line- If JSON contains an input key, it overwrites the raw line value Create one worktree for claude and one for gemini with a focused prompt workmux add my-feature -a claude -a gemini -p "Implement the new search API integration" Generates worktrees: my-feature-claude, my-feature-gemini Create 2 instances of the default agent workmux add my-feature -n 2 -p "Implement task {{ num }} in TASKS.md" Generates worktrees: my-feature-1, my-feature-2 Create worktrees from a variable matrix workmux add my-feature --foreach "platform:iOS,Android" -p "Build for {{ platform }}" Generates worktrees: my-feature-ios, my-feature-android Create agent-specific worktrees via --foreach workmux add my-feature --foreach "agent:claude,gemini" -p "Implement the dashboard refactor" Generates worktrees: my-feature-claude, my-feature-gemini Use frontmatter in a prompt file for cleaner syntax task.md contains: --- foreach: env: staging, production task: smoke-tests, integration-tests --- Run {{ task }} against the {{ env }} environment workmux add testing --prompt-file task.md Generates worktrees: testing-staging-smoke-tests, testing-production-integration-tests Pipe input from stdin to create worktrees review.md contains: Review the {{ input }} module for security issues. echo -e "auth\npayments\napi" | workmux add review -A -P review.md Generates worktrees with LLM-generated branch names for each module Combine stdin input, prompt templating, and concurrency limits to create a worker pool that processes items from an external command. Example: Generate test scaffolding for untested files generate-tests.md contains: Read the file at {{ input }} and generate a test suite covering the exported functions. Focus on happy path and edge cases. When done, run: workmux remove --keep-branch find src/utils -name " .ts" -name " .test.ts" | \ workmux add add-tests \ --branch-template '{{ base name }}-{{ index }}' \ --prompt-file generate-tests.md \ --max-concurrent 3 \ --background find ... lists files without tests one per line piped to stdin --branch-template uses {{ index }} for unique branch names --prompt-file uses {{ input }} to pass each file path to the agent --max-concurrent 3 limits parallel agents to avoid rate limits --background runs without switching focus Merges a branch into a target branch main by default and automatically cleans up all associated resources worktree, tmux window, and local branch . Tip merge vs remove : Use merge when you want to merge directly without a pull request. If your workflow uses pull requests, use to clean up after your PR is merged on the remote. workmux-remove-name-alias-rm remove branch-name : Optional name of the branch to merge. If omitted, automatically detects the current branch from the worktree you're in. --into <branch : 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 : Commit any staged changes before merging without opening an editor --keep , -k : Keep the worktree, window, and branch after merging skip cleanup . Useful when you want to verify the merge before cleaning up. --cleanup : Clean up after merging, overriding merge keep: true . --notification : Show a system notification on successful merge. Useful when delegating merge to an AI agent and you want to be notified when it completes. By default, workmux merge performs a standard merge commit configurable via merge strategy . You can override the configured behavior with these mutually exclusive flags: --rebase : 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 . --squash : 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. If you don't want to have merge commits in your main branch, use the rebase merge strategy, which does --rebase by default. ~/.config/workmux/config.yaml merge strategy: rebase To keep the worktree, window, and branch after every merge unless overridden, set: merge keep: true Use workmux merge --cleanup to clean up for a single merge when this default is enabled. - Determines which branch to merge specified branch or current branch if omitted - Determines the target branch --into or main branch from config - Checks for uncommitted changes errors if found, unless --ignore-uncommitted is used - Commits staged changes if present unless --ignore-uncommitted is used - Merges your branch into the target using the selected strategy default: merge commit - Deletes the tmux window unless keep behavior is enabled via --keep or merge keep: true - Removes the worktree unless keep behavior is enabled via --keep or merge keep: true - Deletes the local branch unless keep behavior is enabled via --keep or merge keep: true When you're done working in a worktree, simply run workmux merge from within that worktree's tmux window. The command will automatically detect which branch you're on, merge it into main, and close the current window as part of cleanup. Merge branch into main default: merge commit workmux merge user-auth Merge the current worktree you're in run this from within the worktree's tmux window workmux merge Rebase onto main before merging for a linear history workmux merge user-auth --rebase Squash all commits into a single commit workmux merge user-auth --squash Merge but keep the worktree/window/branch to verify before cleanup workmux merge user-auth --keep ... verify the merge in main ... workmux remove user-auth clean up later when ready Merge into a different branch stacked PRs workmux merge feature/subtask --into feature/parent Rebases 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. name : Optional worktree name or branch. If omitted, workmux detects the current worktree from the current directory. - Determines which worktree branch to rebase - Reads the saved base branch recorded when the worktree was created - Falls back to the configured main branch when the saved base is not a local branch - Runs git rebase <base inside the worktree - Leaves the worktree, window, and branch in place workmux rebase user-auth workmux rebase Removes 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. name ... : One or more worktree names the directory names . Defaults to current directory name if omitted. --all : Remove all worktrees at once except the main worktree . Prompts for confirmation unless --force is used. Safely skips worktrees with uncommitted changes or unmerged commits. --gone : Remove worktrees whose upstream remote branch has been deleted e.g., after a PR is merged on GitHub . Automatically runs git fetch --prune first. --force , -f : Skip confirmation prompt and ignore uncommitted changes --keep-branch , -k : Remove only the worktree and tmux window while keeping the local branch Remove the current worktree run from within the worktree workmux remove Remove a specific worktree with confirmation if unmerged workmux remove experiment Remove multiple worktrees at once workmux rm feature-a feature-b feature-c Remove multiple worktrees with force no confirmation workmux rm -f old-work stale-branch Use the alias workmux rm old-work Remove worktree/window but keep the branch workmux remove --keep-branch experiment Force remove without prompts workmux rm -f experiment Remove worktrees whose remote branches were deleted e.g., after PR merge workmux rm --gone Force remove all gone worktrees no confirmation workmux rm --gone -f Remove all worktrees at once workmux rm --all Renames a worktree's directory, its tmux window or session, and the per-worktree workmux metadata. Optionally also renames the underlying git branch. old-name : Optional current worktree name. Defaults to the current worktree when run from inside one. <new-name : The new handle directory name and tmux window/session base name . --branch , -b : Also rename the underlying git branch to match <new-name . Fails if the worktree is on a detached HEAD. Rename a worktree from inside it workmux rename feature-new Rename a specific worktree by name workmux rename feature-old feature-new Also rename the branch to match workmux rename feature-old feature-new --branch Rename 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. Lists all git worktrees with their agent status, multiplexer window status, and merge status. Supports filtering by worktree handle or branch name. worktree-or-branch... : Filter by worktree handle directory name or branch name. Accepts multiple values. When omitted, shows all worktrees. --pr : Show GitHub PR status for each worktree. Requires the gh CLI 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 : Output as JSON. Produces a JSON array of objects with fields: handle , branch , path , is main , mode , has uncommitted changes , is open , created at . List all worktrees workmux list List with PR status workmux list --pr Output as JSON for scripting workmux list --json Filter to specific worktrees workmux list my-feature workmux list feature-auth feature-api BRANCH AGE AGENT MUX UNMERGED PATH main - - - - ~/project user-auth 2h 🤖 ✓ - ~/project worktrees/user-auth bug-fix 3d ✅ ✓ ● ~/project worktrees/bug-fix api-work 1w - ✓ - ~/project worktrees/api-work - AGE shows how old the worktree is e.g., 2h , 3d , 1w , 2mo - AGENT shows the current agent status see status tracking https://workmux.dev/guide/status-tracking/ : 🤖 = working, 💬 = waiting for input, ✅ = finished- Multiple agents per worktree show a count e.g., 2🤖 1✅ ✓ in MUX column = multiplexer window exists for this worktree ● in UNMERGED column = branch has commits not merged into main - = not applicable Opens the global configuration file ~/.config/workmux/config.yaml in your preferred editor. Uses $VISUAL , $EDITOR , or falls back to vi . Creates the file with commented-out defaults if it doesn't exist yet. Prints the path to the global configuration file. Useful for scripting. Prints the default configuration file with all options documented. Useful for discovering available options or piping to an AI agent for context. Generates .workmux.yaml with example configuration and "<global " placeholder usage. Opens 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. name... : One or more worktree names the directory name, which is also the tmux window name without the prefix . Optional with --new when run from inside a worktree. -n, --new : Force opening in a new window even if one already exists. Creates a duplicate window with a suffix e.g., -2 , -3 . 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 : Open in session mode, overriding the stored mode. Persists the mode change for subsequent opens. Cannot be combined with --new . Only supported with tmux. --config <path : Use an alternate config file for this invocation. Still merges with global config. --run-hooks : Re-runs the post create commands these block window creation . --force-files : Re-applies file copy/symlink operations. Useful for restoring a deleted .env file. -p, --prompt <text : Provide an inline prompt for AI agent panes. -P, --prompt-file <path : Provide a path to a file containing the prompt. -c, --continue : Resume the agent's most recent conversation in this worktree. Injects the appropriate flag for the configured agent e.g., --continue for Claude, --resume for Gemini . -e, --prompt-editor : Open your editor to write the prompt interactively. --prompt-file-only : Write the prompt file without injecting it into agent commands. - Verifies that a worktree with <name exists. - If a tmux window exists and --new is 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. - If specified Runs file operations and post create hooks. - Sets up your configured tmux pane layout. - Automatically switches your tmux client to the new window. Open or switch to a window for an existing worktree workmux open user-auth Force open a second window for the same worktree creates user-auth-2 workmux open user-auth --new Open a new window for the current worktree run from within the worktree workmux open --new Open in session mode converts from window mode if needed workmux open user-auth --session Resume the agent's last conversation workmux open user-auth --continue Resume and send a follow-up prompt workmux open user-auth --continue -p "Continue implementing the login flow" Open and re-run dependency installation workmux open user-auth --run-hooks Open and restore configuration files workmux open user-auth --force-files Open multiple worktrees at once workmux open user-auth api-refactor bugfix-login Closes 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. name : Optional worktree name the directory name . Defaults to current directory if omitted. Close the window for a specific worktree workmux close user-auth Close the current worktree's window run from within the worktree workmux close To reopen the window later, use workmux open workmux-open-name . Tip : You can also use tmux's native kill-window command default: prefix + & to close a worktree's window with the same effect. Restores worktree windows after a tmux or computer crash. Uses persisted agent state files to detect which worktrees had active agents before the crash, then reopens them with --continue to resume agent conversations. --dry-run : Show what would be restored without doing it. See what would be restored after a crash workmux resurrect --dry-run Restore all worktrees that had agents running workmux resurrect - Reads agent state files from ~/.local/state/workmux/agents/ - Matches each state file's working directory to a git worktree in the current repo - Skips worktrees that are already open or no longer exist - Opens each matched worktree with --continue to resume the agent Re-applies file operations copy and symlink from files config to existing worktrees. Useful when you add new entries to the files config or a symlink was accidentally deleted. --all : Sync all worktrees instead of just the current one. Sync files to the current worktree workmux sync-files Sync files to all worktrees workmux sync-files --all Prints the filesystem path of an existing worktree. Useful for scripting or quickly navigating to a worktree directory. <name : Worktree name the directory name . Get the path of a worktree workmux path user-auth Output: /Users/you/project worktrees/user-auth Use in scripts or with cd cd "$ workmux path user-auth " Copy a file to a worktree cp config.json "$ workmux path feature-branch /" Opens a TUI dashboard showing all active AI agents across all tmux sessions. Useful for monitoring multiple parallel agents and quickly jumping between them. -d, --diff : 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 : Set preview pane size as percentage larger = more preview, less table . Default: 60. -s, --session : 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 : Open directly on the specified tab. Important This feature requires agent status tracking agent-status-tracking to be configured. Without it, no agents will appear in the dashboard. | Key | Action | |---|---| 1 - 9 | Quick jump to agent closes dashboard | Tab | Toggle between current and last agent | d | View diff opens WIP view | o | Open PR in browser | p | Peek at agent dashboard stays open | s | Cycle sort mode | / | Filter agents by name | F | Toggle session filter | f | Toggle stale filter show/hide stale | i | Enter input mode type to agent | Ctrl+u | Scroll preview up | Ctrl+d | Scroll preview down | + / - | Resize preview pane | Enter | Go to selected agent closes dashboard | j / k | Navigate up/down | : | Open command palette | q / Esc | Quit | The bottom half shows a live preview of the selected agent's terminal output. The preview auto-scrolls to show the latest output, but you can scroll through history with Ctrl+u / Ctrl+d . Press i to enter input mode and type directly to the agent without leaving the dashboard. : Quick jump key 1-9 Project : Project name from worktrees path 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 Press s to cycle through sort modes: 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 Your sort preference persists in the tmux session. Press F to toggle the session filter. When active, only agents in the current session are shown. This is useful for session-per-project workflows where each session maps to a repository. You can also start the dashboard with --session to default to session filtering. The preference persists across sessions. Press / to activate the name filter. Type to filter the agent list by project or worktree name case-insensitive . Press Enter to accept the filter and return to normal navigation, or Esc to clear the filter. When a filter is active, it is shown in the footer bar. Press f to toggle between showing all agents or hiding stale ones. The filter state persists across dashboard sessions within the same tmux server. Press d to view the diff for the selected agent. The diff view has two modes: WIP - Shows uncommitted changes git diff HEAD review - Shows all changes on the branch vs main git diff main...HEAD Press Tab to toggle between modes. The footer displays which mode is active along with diff statistics showing lines added + and removed - . | Key | Action | |---|---| Tab | Toggle WIP / review | a | Enter patch mode WIP only | j / k | Scroll down/up | Ctrl+d | Page down | Ctrl+u | Page up | c | Send commit command to agent | m | Trigger merge and exit dashboard | : | Open command palette | q / Esc | Close diff view | Patch mode a from WIP diff allows staging individual hunks like git add -p . This is useful for selectively staging parts of an agent's work. When delta https://github.com/dandavison/delta is installed, hunks are rendered with syntax highlighting for better readability. | Key | Action | |---|---| y | Stage current hunk | n | Skip current hunk | u | Undo last staged hunk | s | Split hunk if splittable | o | Comment on hunk sends to agent | j / k | Navigate to next/previous hunk | : | Open command palette | q / Esc | Exit patch mode | Press y to stage the current hunk and advance to the next. Press n to skip without staging. The counter in the header shows your progress e.g., 3/10 . Press s to split the current hunk into smaller pieces when there are context lines between separate changes. Press u to undo the last staged hunk. Press o to comment on the current hunk. This sends a message to the agent including the file path, line number, the diff hunk as context, and your comment. Useful for giving feedback like "This function should handle the error case". Add to your ~/.tmux.conf for quick access: bind C-s display-popup -h 30 -w 100 -E "workmux dashboard" Open directly on Worktrees tab bind C-w display-popup -h 30 -w 100 -E "workmux dashboard --tab worktrees" Then press prefix + Ctrl-s to open the dashboard as a tmux popup. Toggles a live agent status sidebar on the left or top edge of all tmux windows. By default, each sidebar pane shows active agents across all tmux sessions with live status updates, providing an always-visible overview without taking over the full screen like the dashboard. Use workmux sidebar filter session to show only agents in the current tmux session. workmux sidebar Toggle sidebar on/off all sessions workmux sidebar --session Toggle current session only, or opt out of global mode workmux sidebar --position top Override configured placement for this toggle The sidebar displays: - Status icon working/waiting/done with spinner animation - Project and worktree name e.g. myproject/fix-bug - Elapsed time since last status change | Key | Action | |---|---| j / k | Navigate up/down | Enter | Jump to agent | g / G | Jump to first/last | v | Toggle layout mode | f | Toggle session filter | q | Quit sidebar | With tmux mouse mode enabled set -g mouse on , click an agent row or top-bar chip to jump to its pane, or scroll to navigate the list. When the global sidebar is active, workmux sidebar --session hides it in the current tmux session only. Run the same command again to show it in that session again while keeping the global sidebar active elsewhere. Configure placement, width, and layout in .workmux.yaml : sidebar: position: left "left" default or "top" width: 40 left width in columns, or "15%" for percentage layout: tiles left only: "compact" or "tiles" default The 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. Use workmux sidebar --position top or --position left to override the configured placement when enabling the sidebar. bind C-t run-shell "workmux sidebar" Then press prefix + Ctrl-t to toggle the sidebar. Note: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. Shows 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. workmux reap-agents workmux reap-agents --hours 48 workmux reap-agents --hours 24 --force Use --force to interrupt matching agents and remove their workmux agent state after they exit. Commands for managing sandbox functionality. See the sandbox guide https://workmux.raine.dev/guide/sandbox/ for full documentation. | Command | Description | |---|---| sandbox pull | Pull the latest container image from the registry | sandbox build | Build the container image locally | sandbox shell | Start an interactive shell inside a sandbox | sandbox agent | Run the configured agent in a sandbox with RPC support | sandbox stop | Stop running Lima VMs | sandbox prune | Delete unused Lima VMs to reclaim disk space | sandbox install-dev | Cross-compile and install workmux into sandboxes dev | Removes stale entries from Claude config ~/.claude.json that point to deleted worktree directories. When you run Claude Code in worktrees, it stores per-worktree settings in that file. Over time, as worktrees are merged or deleted, it can accumulate entries for paths that no longer exist. - Scans ~/.claude.json for entries pointing to non-existent directories - Creates a backup at ~/.claude.json.bak before making changes - Removes all stale entries - Reports the number of entries cleaned up - Only removes entries for absolute paths that don't exist - Creates a backup before modifying the file - Preserves all valid entries and relative paths Clean up stale Claude Code entries workmux claude prune - Removing: /Users/user/project worktrees/old-feature ✓ Created backup at ~/.claude.json.bak ✓ Removed 3 stale entries from ~/.claude.json Generates shell completion script for the specified shell. Completions provide tab-completion for commands and dynamic branch name suggestions. <shell : Shell type: bash , zsh , or fish . Generate completions for zsh workmux completions zsh See the Shell Completions shell-completions section for installation instructions. Displays this README with terminal formatting. Useful for quick reference without leaving the terminal. When run interactively, renders markdown with colors and uses a pager less . When piped e.g., to an LLM , outputs raw markdown for clean context. You can ask an agent to read the docs and configure workmux for you: run workmux docs and configure workmux so that on the left pane there is claude as agent, and on the right side neovim and empty shell on top of each other ⏺ Bash workmux docs ⎿ <p align="center" <picture … +923 lines ⏺ Write .workmux.yaml ⎿ Wrote 9 lines to .workmux.yaml ⏺ Created .workmux.yaml with the layout: - Left: claude agent focused - Right top: neovim - Right bottom: empty shell Workmux 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. - 🤖 = agent is working - 💬 = agent is waiting for user input - ✅ = agent finished auto-clears on window focus | Agent | Status | |---|---| | Claude Code | ✅ Supported | | OpenCode | ✅ Supported | | Codex | ✅ Supported | | Copilot CLI | ✅ Supported | | Pi | ✅ Supported | | Oh My Pi | ✅ Supported | | Gemini CLI | ✅ Supported | | Kiro | | Tracking issue https://github.com/mistralai/mistral-vibe/discussions/334 Notes: 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 Run workmux setup to automatically detect Claude Code, Copilot CLI, OpenCode, Pi, Oh My Pi, and other supported agent CLIs, install status tracking hooks, and install skills: workmux setup You can also run specific parts: workmux setup --hooks or workmux setup --skills . For Claude Code, CLAUDE CONFIG DIR is respected for both hook and skill installation. Workmux will also prompt you on first run if it detects an agent without status tracking or skills configured. Workmux automatically modifies your tmux window-status-format to display the status icons. This happens once per session and only affects the current tmux session not your global config . If you prefer manual setup: Claude Code : install the workmux status plugin: claude plugin marketplace add raine/workmux claude plugin install workmux-status Or manually add the hooks to ~/.claude/settings.json . See .claude-plugin/plugin.json /raine/workmux/blob/main/.claude-plugin/plugin.json for the hook configuration. Copilot CLI : copy the hooks to your repository: mkdir -p .github/hooks/workmux-status curl -o .github/hooks/workmux-status/hooks.json \ https://raw.githubusercontent.com/raine/workmux/main/.github/hooks/workmux-status/hooks.json Note: Copilot hooks are per-repository. The waiting state is not supported due to limitations in the Copilot CLI hooks implementation. OpenCode : download the workmux status plugin: mkdir -p ~/.config/opencode/plugins curl -o ~/.config/opencode/package.json \ https://raw.githubusercontent.com/raine/workmux/main/resources/opencode/package.json curl -o ~/.config/opencode/plugins/workmux-status.ts \ https://raw.githubusercontent.com/raine/workmux/main/resources/opencode/plugins/workmux-status.ts Restart OpenCode for the plugin to take effect. Oh My Pi : copy the workmux status extension to your global OMP extensions directory: mkdir -p ~/.omp/agent/extensions curl -o ~/.omp/agent/extensions/workmux-status.ts \ https://raw.githubusercontent.com/raine/workmux/main/.omp/extensions/workmux-status.ts Restart omp for the extension to take effect. You can customize the icons in your config: ~/.config/workmux/config.yaml status icons: working: '🔄' waiting: '⏸️' done: '✔️' If you prefer to manage the tmux format yourself, disable auto-modification and add the status variable to your ~/.tmux.conf : ~/.config/workmux/config.yaml status format: false ~/.tmux.conf set -g window-status-format ' I: W {?@workmux status, {@workmux status},} {?window flags, {window flags}, }' set -g window-status-current-format ' I: W {?@workmux status, {@workmux status},} {?window flags, {window flags}, }' Use workmux last-done to quickly switch to the agent that most recently finished its task or is waiting for user input. Repeated invocations cycle through all completed and waiting agents in reverse chronological order. Add a tmux keybinding for quick access: ~/.tmux.conf bind-key L run-shell "workmux last-done" Then press prefix + L to jump to the last completed or waiting agent, press again to cycle to the next oldest, and so on. Use workmux last-agent to toggle between your current agent and the last one you visited. This works like vim's Ctrl+^ or tmux's last-window - it remembers which agent you came from and switches back to it. Pressing it again returns you to where you were. This is available both as a CLI command and as the Tab key in the dashboard. Add a tmux keybinding for quick access: ~/.tmux.conf bind Tab run-shell "workmux last-agent" Then press prefix + Tab to toggle between your two most recent agents. workmux can run agents inside containers Docker/Podman/Apple Container or Lima VMs, isolating them from your host. Agents are restricted to the project worktree; sensitive files like SSH keys, AWS credentials, and other secrets are not accessible. This lets you run agents with --dangerously-skip-permissions without worrying about what they might touch on your host. Sandboxing is transparent: status indicators, the dashboard, spawning new agents, and merging all continue to work normally across the sandbox boundary. | Container Docker/Podman/Apple Container | Lima VM | | |---|---|---| Isolation | Process/VM-level | Machine-level virtual machine | Persistence | Ephemeral new container per session | Persistent stateful VMs | Toolchain | Custom Dockerfile or host command proxying | Built-in Nix & Devbox support | Network | Optional restrictions domain allowlist | Unrestricted | Container 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. ~/.config/workmux/config.yaml or .workmux.yaml sandbox: enabled: true backend: lima uncomment for Lima VMs default: container The pre-built container image is pulled automatically on first run. For Lima, the VM is created and provisioned on first use. Both backends support: Host command proxying : Run specific commands build tools, linters on the host from inside the sandbox via host commands config Extra mounts : Mount additional host directories into the sandbox read-only by default Git identity : Your user.name and user.email are automatically injected so git commits work without exposing your full ~/.gitconfig Credential sharing : Agent credentials are shared between host and sandbox Network restrictions container only : Block outbound connections except to approved domains See the sandbox guide https://workmux.raine.dev/guide/sandbox/ for full setup, configuration, and security details. By default, workmux creates tmux windows within your current session. With session mode, each worktree gets its own tmux session instead. This allows each worktree to have multiple windows. Add to your config: ~/.config/workmux/config.yaml or .workmux.yaml mode: session Or use the --session flag: workmux add feature-branch --session Persistence : The mode is stored per-worktree. If you create a worktree with --session , subsequent open / close / remove commands automatically use session mode for that worktree. Navigation : After merge or remove , workmux switches you back to the previous session. Use the windows config to launch multiple windows in each session. Each window can have its own pane layout. This is mutually exclusive with the top-level panes config. mode: session windows: - name: editor panes: - command: <agent focus: true - split: horizontal size: 20 - name: tests panes: - command: just test --watch - panes: - command: tail -f app.log Each window supports: | Option | Description | Default | |---|---|---| name | Window name if omitted, tmux auto-names from command | Auto | panes | Pane layout same syntax as top-level panes | Single shell | focus: true works across windows: the last pane with focus set determines which window is selected when the session opens. 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 , -3 suffixes , session mode creates one session per worktree. Here's a complete workflow: Start a new feature workmux add user-auth Work on your feature... tmux automatically sets up your configured panes and environment When ready, merge and clean up workmux merge user-auth Start another feature workmux add api-endpoint List all active worktrees workmux list workmux turns a multi-step manual workflow into simple commands, making parallel development workflows practical. 1. Manually create the worktree and environment git worktree add ../worktrees/user-auth -b user-auth cd ../worktrees/user-auth cp ../../project/.env.example .env ln -s ../../project/node modules . npm install ... and other setup steps 2. Manually create and configure the tmux window tmux new-window -n user-auth tmux split-window -h 'npm run dev' tmux send-keys -t 0 'claude' C-m ... repeat for every pane in your desired layout 3. When done, manually merge and clean everything up cd ../../project git switch main && git pull git merge --no-ff user-auth tmux kill-window -t user-auth git worktree remove ../worktrees/user-auth git branch -d user-auth Create the environment workmux add user-auth ... work on the feature ... Merge and clean up workmux merge Run multiple AI agents simultaneously, each in its own worktree. Spin up two agents working on different tasks workmux add refactor-user-model -p "Refactor the User model to use composition" workmux add add-search-endpoint -p "Add a /search endpoint with pagination" Each agent works in isolation. Check progress via tmux windows or the dashboard workmux dashboard Merge completed work back to main workmux merge refactor-user-model workmux merge add-search-endpoint Tip Use -A --auto-name to generate branch names automatically from your prompt, so you don't have to think of one. See Automatic branch name generation automatic-branch-name-generation . Git worktrees https://git-scm.com/docs/git-worktree let you have multiple branches checked out at once in the same repository, each in a separate directory. This provides two main advantages over a standard single-directory setup: - Painless context switching : Switch between tasks just by changing directories cd ../other-branch . There's no need to git stash or make temporary commits. Your work-in-progress, editor state, and command history remain isolated and intact for each branch. - True parallel development : Work on multiple branches simultaneously without interference. You can run builds, install dependencies npm install , 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. In a standard Git setup, switching branches disrupts your flow by requiring a clean working tree. Worktrees remove this friction. workmux automates the entire process and pairs each worktree with a dedicated tmux window, creating fully isolated development environments. See Before and after before-and-after for how workmux streamlines this workflow. While 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. 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 trailing slashes When git worktree add creates a new working directory, it's a clean checkout. Files listed in your .gitignore e.g., .env files, node modules , IDE configuration will not exist in the new worktree by default. Your application will be broken in the new worktree until you manually create or link these necessary files. This is a primary feature of workmux. Use the files section in your .workmux.yaml to automatically copy or symlink these files on creation: .workmux.yaml files: copy: - .env Copy environment variables symlink: - .next/cache Share Next.js build cache Note: Symlinking node modules can be efficient but only works if all worktrees share identical dependencies. If different branches have different dependency versions, each worktree needs its own installation. For dependency installation, consider using a pane command instead of post create hooks - this runs the install in the background without blocking the worktree and window creation: panes: - command: npm install focus: true - split: horizontal Worktrees 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. The 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. Modern package managers like pnpm use a global store with symlinks to node modules . Each worktree typically needs its own pnpm install to set up the correct dependency versions for that branch. If your worktrees always have identical dependencies e.g., working on multiple features from the same base , you could potentially symlink node modules between worktrees. However, this breaks as soon as branches diverge in their dependencies, so it's generally safer to run a fresh install in each worktree. Note: In large monorepos, cleaning up node modules during worktree removal can take significant time. workmux has a special cleanup mechanism https://github.com/raine/workmux/blob/main/src/scripts/cleanup node modules.sh that moves node modules to a temporary location and deletes it in the background, making the remove command return almost instantly. Unlike node modules , Rust's target/ directory should not be symlinked between worktrees. Cargo locks the target directory during builds, so sharing it would block parallel builds and defeat the purpose of worktrees. Instead, use sccache https://github.com/mozilla/sccache to share compiled dependencies across worktrees: brew install sccache Add to ~/.cargo/config.toml : build rustc-wrapper = "sccache" This caches compiled dependencies globally, so new worktrees benefit from cached artifacts without any lock contention. When running multiple services API, web app, database in a monorepo, each worktree needs unique ports to avoid conflicts. For example, if your .env has hardcoded ports like API PORT=3001 and VITE PORT=3000 , running two worktrees simultaneously would fail because both would try to bind to the same ports. Simply copying .env files won't work since all worktrees would use the same ports. Solution : Use a post create hook to generate a .env.local file with unique ports. Many frameworks Vite, Next.js, CRA automatically load .env.local and merge it with .env , with .env.local taking precedence. For plain Node.js, use multiple --env-file flags where later files override earlier ones. Create a script at scripts/worktree-env : bash /usr/bin/env bash set -euo pipefail port in use { lsof -nP -iTCP:"$1" -sTCP:LISTEN & /dev/null } find port { local port=$1 while port in use "$port"; do port++ done echo "$port" } Hash the handle to get a deterministic port offset 0-99 hash=$ echo -n "$WM HANDLE" | md5 | cut -c1-4 offset=$ 16 $hash % 100 Find available ports starting from the hash-based offset api port=$ find port $ 3001 + offset 10 vite port=$ find port $ 3000 + offset 10 Generate .env.local with port overrides cat .env.local <<EOF API PORT=$api port VITE PORT=$vite port VITE PUBLIC API URL=http://localhost:$api port EOF echo "Created .env.local with ports: API=$api port, VITE=$vite port" Configure workmux to copy .env and generate .env.local : .workmux.yaml files: copy: - .env Copy secrets DATABASE URL, API keys, etc. post create: - ./scripts/worktree-env Generate .env.local with unique ports For plain Node.js without framework support , load both files with later overriding earlier: { "scripts": { "api": "node --env-file=.env --env-file=.env.local api/server.js", "web": "node --env-file=.env --env-file=.env.local web/server.js" } } Each worktree now gets unique ports derived from its name, allowing multiple instances to run simultaneously without conflicts. The .env file stays untouched, and .env.local is gitignored. See the Monorepos guide https://workmux.raine.dev/guide/monorepos for alternative approaches using direnv. If your .gitignore uses a trailing slash to ignore directories e.g., tests/venv/ , symlinks to that path in the created worktree will not be ignored and will show up in git status . This is because venv/ only matches directories, not files symlinks . To ignore both directories and symlinks, remove the trailing slash: - tests/venv/ + tests/venv On first run, workmux prompts you to check if a git branch icon displays correctly. If you have a Nerd Font https://www.nerdfonts.com/ installed, answer yes to enable nerdfont icons throughout the interface, including the tmux window prefix. To change the setting later, edit ~/.config/workmux/config.yaml : nerdfont: true or false for unicode fallbacks If your project uses direnv https://direnv.net/ for environment management, you can configure workmux to automatically set it up in new worktrees: .workmux.yaml post create: - direnv allow files: symlink: - .envrc By default, Claude Code prompts for permission before running commands. There are several ways to handle this in worktrees: Share permissions across worktrees To keep permission prompts but share granted permissions across worktrees: files: symlink: - .claude/settings.local.json Add this to your global config ~/.config/workmux/config.yaml or project's .workmux.yaml . Since this file contains user-specific permissions, also add it to .gitignore : .claude/settings.local.json Named agent profiles Define named agents https://workmux.raine.dev/guide/agents named-agents in your global config when an agent needs a wrapper command, extra arguments, or environment variables. Simple string aliases still work: ~/.config/workmux/config.yaml agents: cc-work: "claude" cc-personal: "env CLAUDE CONFIG DIR=~/.claude-personal claude" cc-bedrock: "env -u CLAUDE CODE USE BEDROCK -u AWS REGION AWS PROFILE=prod claude" cc-yolo: "claude --dangerously-skip-permissions" cod: "codex --yolo" Structured profiles make the same kind of config easier to maintain because arguments and environment are not written as one long shell string: ~/.config/workmux/config.yaml agents: cc-personal: type: claude command: claude env: CLAUDE CONFIG DIR: ~/.claude-personal ANTHROPIC AUTH TOKEN: from env: ANTHROPIC AUTH TOKEN cod-mini: type: codex command: codex args: - exec - -m - gpt-5.1-codex-mini To skip prompts entirely, define a named agent with the Claude skip-permissions flag: ~/.config/workmux/config.yaml agents: cc-yolo: type: claude command: claude args: - --dangerously-skip-permissions Reference a named profile per project with agent: cc-yolo , pass it with -a cc-yolo , or use it directly in a pane with <agent:cc-yolo . Structured profiles support command , args , env , and type fields. The /worktree skill https://workmux.raine.dev/guide/skills lets you delegate tasks to parallel worktree agents directly from your conversation. A main agent on the main branch can act as a coordinator: planning work and spinning up worktree agents for each task. 📝 See this blog post for a detailed walkthrough of the workflow. /worktree Implement user authentication /worktree Fix the race condition in handler.go /worktree Add dark mode, Implement caching multiple tasks See the Skills guide https://workmux.raine.dev/guide/skills for more skills including /merge , /rebase , /coordinator , and /open-pr . To enable tab completions for commands and branch names, add the following to your shell's configuration file. For bash , add to your .bashrc : eval "$ workmux completions bash " For zsh , add to your .zshrc : eval "$ workmux completions zsh " For fish , add to your config.fish : workmux completions fish | source - Rust for building - Git 2.5+ for worktree support - tmux or an alternative backend While tmux is the primary and recommended backend, workmux also supports alternative terminal multiplexers: 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 and listen on configuration. experimental - For users who prefer Zellij. Detected automatically via Zellij https://workmux.raine.dev/guide/zellij $ZELLIJ . workmux auto-detects the backend from environment variables $TMUX , $WEZTERM PANE , $KITTY WINDOW ID , or $ZELLIJ . Session-specific variables are checked first, so running tmux inside kitty correctly selects the tmux backend. Set $WORKMUX BACKEND to override detection. workmux is inspired by wtp https://github.com/satococoa/wtp , an excellent git worktree management tool. While wtp streamlines worktree creation and setup, workmux takes this further by tightly coupling worktrees with tmux window management. For managing multiple AI agents in parallel, tools like claude-squad https://github.com/smtg-ai/claude-squad and vibe-kanban https://github.com/BloopAI/vibe-kanban/ offer dedicated interfaces, like a TUI or kanban board. In contrast, workmux adheres to its philosophy that tmux is the interface , providing a native tmux experience for managing parallel workflows without requiring a separate interface to learn. Bug 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 See CONTRIBUTING.md /raine/workmux/blob/main/CONTRIBUTING.md for development setup. 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