`: Shell type: `bash`, `zsh`, or `fish`.
#### Examples
```bash
# Generate completions for zsh
workmux completions zsh
```
See the [Shell Completions](#shell-completions) section for installation
instructions.
---
### `workmux docs`
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.
#### Using with AI agents
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)
βΏ
β¦ +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
```
## Agent status tracking
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.

#### Key
- π€ = 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 |
| Grok | β
Supported |
| Antigravity CLI (`agy`) | β
Supported\* |
| Kiro | [Tracking issue](https://github.com/kirodotdev/Kiro/issues/5440) |
| Mistral Vibe | [Tracking issue](https://github.com/mistralai/mistral-vibe/discussions/334) |
**Notes:**
- **Copilot CLI**: π¬ waiting state requires Copilot CLI 1.0.18 or later
- **Pi**: No π¬ waiting state
- **Antigravity CLI (`agy`)**: No π¬ waiting state
- **Kiro**: Hooks support is messy: requires a custom agent since the default
can't be edited
### Setup
Run `workmux setup` to automatically detect Claude Code, Antigravity CLI,
Copilot CLI, OpenCode, Pi, Oh My Pi, Grok, and other supported agent CLIs, install
status tracking hooks, and install skills:
```bash
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).
#### Manual setup
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](.claude-plugin/plugin.json) for the hook
configuration.
**Copilot CLI**: with Copilot CLI 0.0.422 or later, install the personal hook:
```bash
mkdir -p ~/.copilot/hooks
curl -o ~/.copilot/hooks/workmux-status.json \
https://raw.githubusercontent.com/raine/workmux/main/resources/copilot/hooks/workmux-status/hooks.json
```
Copilot loads personal hooks in every repository. If the repository contains a
`.github/hooks/workmux-status` installation, remove that directory to avoid
running both copies of the hook. The waiting state requires Copilot CLI 1.0.18
or later.
**Antigravity CLI (`agy`)**: `workmux setup` installs lifecycle hooks in
`~/.gemini/config/hooks.json`. `PreInvocation` marks the pane working, and the
terminal `Stop` event marks it done.
**OpenCode**: run `workmux setup --hooks`. For manual installation, see the
[OpenCode setup guide](https://workmux.dev/guide/status-tracking/#opencode-setup).
V2 status tracking requires the terminal UI; headless `opencode run` is not tracked.
**Oh My Pi**: copy the workmux status extension to your global OMP extensions directory:
```bash
mkdir -p ~/.omp/agent/extensions
curl -o ~/.omp/agent/extensions/workmux-status.ts \
https://raw.githubusercontent.com/raine/workmux/main/resources/omp/extensions/workmux-status.ts
```
Restart omp for the extension to take effect.
### Customization
You can customize the icons in your config:
```yaml
# ~/.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`:
```yaml
# ~/.config/workmux/config.yaml
status_format: false
```
```bash
# ~/.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}, }'
```
### Jump to completed or waiting agents
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:
```bash
# ~/.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.
### Toggle between agents
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:
```bash
# ~/.tmux.conf
bind Tab run-shell "workmux last-agent"
```
Then press `prefix + Tab` to toggle between your two most recent agents.
## Sandbox
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.
### Backends
| | 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.
### Quick start
```yaml
# ~/.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.
### Shared features
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.dev/guide/sandbox/) for full
setup, configuration, and security details.
## Session mode
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.
### Enabling session mode
Add to your config:
```yaml
# ~/.config/workmux/config.yaml or .workmux.yaml
mode: session
```
Or use the `--session` flag:
```bash
workmux add feature-branch --session
```
### How it works
- **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.
### Returning to a default session
By default a client viewing a closing session returns to whichever session it
was in previously. Set `default_session` to name a session to prefer instead:
```yaml
mode: session
default_session: main
```
`close`, `remove` and `merge` then send clients to the `main` session. A managed
session for the destination branch still wins, so this applies only where tmux
would otherwise fall back to the previous session. The value is a literal tmux
session name, so `window_prefix` is not applied and it can name a session
workmux does not manage; if nothing matches it exactly, clients fall back to
their previous sessions as before.
### Multiple windows per 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.
```yaml
mode: session
windows:
- name: editor
panes:
- command:
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.
### Limitations
- **tmux and Rex only**: Session mode is currently only supported for the tmux and Rex backends.
- **No duplicates**: Unlike window mode which supports opening multiple windows
for the same worktree (`-2`, `-3` suffixes), session mode creates one session
per worktree.
## Workflow example
Here's a complete workflow:
```bash
# 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
```
## Before and after
workmux turns a multi-step manual workflow into simple commands, making parallel
development workflows practical.
### Without workmux
```bash
# 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
```
### With workmux
```bash
# Create the environment
workmux add user-auth
# ... work on the feature ...
# Merge and clean up
workmux merge
```
### The parallel AI workflow
Run multiple AI agents simultaneously, each in its own worktree.
```bash
# 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).
## Why git worktrees?
[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.
## Git worktree caveats
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 `.gitignore` trailing slashes](#symlinks-and-gitignore-trailing-slashes)
### Gitignored files require configuration
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:
```yaml
# .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:
```yaml
panes:
- command: npm install
focus: true
- split: horizontal
```
### Conflicts
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.
### Package manager considerations (pnpm, yarn)
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. It is enabled
automatically when a lockfile (`pnpm-lock.yaml`, `package-lock.json`, or
`yarn.lock`) exists at the project root or in a direct subdirectory. You can also
request it explicitly with `""` in `pre_remove`.
### Rust projects
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:
```bash
brew install sccache
```
Add to `~/.cargo/config.toml`:
```toml
[build]
rustc-wrapper = "sccache"
```
This caches compiled dependencies globally, so new worktrees benefit from cached
artifacts without any lock contention.
### Port conflicts in monorepos
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 <`. Structured
profiles support `command`, `args`, `env`, and `type` fields.
### Delegating tasks with `/worktree`
The `/worktree` [skill](https://workmux.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](https://raine.dev/blog/git-worktrees-parallel-agents/)** for a
detailed walkthrough of the workflow.
#### Usage
```
> /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.dev/guide/skills) for more skills
including `/merge`, `/rebase`, `/coordinator`, and `/open-pr`.
## Shell completions
To enable tab completions for commands and branch names, add the following to
your shell's configuration file.
For **bash**, add to your `.bashrc`:
```bash
eval "$(workmux completions bash)"
```
For **zsh**, add to your `.zshrc`:
```bash
eval "$(workmux completions zsh)"
```
For **fish**, add to your `config.fish`:
```bash
workmux completions fish | source
```
## Requirements
- Rust (for building)
- Git 2.5+ (for worktree support)
- tmux (or an alternative backend)
### Alternative backends
While tmux is the primary and recommended backend, workmux also supports
alternative terminal multiplexers:
- **[WezTerm](https://workmux.dev/guide/wezterm)** (experimental) - For
users who prefer WezTerm's features. Thanks to
[@JeremyBYU](https://github.com/JeremyBYU) for contributing this backend.
- **[kitty](https://workmux.dev/guide/kitty)** (experimental) - For users
who prefer kitty terminal. Requires `allow_remote_control` and `listen_on`
configuration.
- **[Zellij](https://workmux.dev/guide/zellij)** (experimental) - For
users who prefer Zellij. Detected automatically via `$ZELLIJ`.
- **[Rex](https://workmux.dev/guide/rex)** (experimental) - For users of
the Rex multiplexer. Detected automatically via `$REX_BLOCK`.
workmux auto-detects the backend from environment variables (`$TMUX`,
`$WEZTERM_PANE`, `$ZELLIJ`, `$KITTY_WINDOW_ID`, or `$REX_BLOCK`).
Session-specific variables are checked first, so running tmux inside kitty or
Rex correctly selects the tmux backend. Set `$WORKMUX_BACKEND` to override
detection.
## Inspiration and related tools
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.
## Contributing
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](CONTRIBUTING.md) for development setup.
## Related projects
- [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