### Workmux Command Example

Source: https://github.com/raine/workmux/blob/main/docs/guide/monorepos.md

This is an example output from the `workmux add` command, showing the process of running setup commands, creating the .env.local file with unique ports, and confirming the successful creation of the worktree and tmux window.

```bash
$ workmux add feature-auth
Running setup commands...
Created .env.local with ports: API=3471, VITE=3470
✓ Setup complete
✓ Successfully created worktree and tmux window for 'feature-auth'
```

--------------------------------

### Complete workflow example

Source: https://github.com/raine/workmux/blob/main/docs/guide/quick-start.md

Demonstrates a typical workflow: adding a new feature, merging it, starting another feature, and listing all active worktrees.

```bash
# Start a new feature
workmux add user-auth

# Work on your feature...
# (workmux 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
```

--------------------------------

### Install rust-release-tools

Source: https://github.com/raine/workmux/blob/main/RELEASE.md

Install the required release tools via pipx.

```bash
pipx install git+https://github.com/raine/rust-release-tools.git
```

--------------------------------

### Install Lima using Homebrew

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/lima.md

Install the Lima virtualization tool using the Homebrew package manager.

```bash
brew install lima
```

--------------------------------

### workmux add with Skipped Setup Steps

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

Shows how to skip specific setup steps like hooks or file operations when creating a worktree, useful for documentation-only changes or quick fixes.

```bash
# Skip expensive setup for documentation-only changes
workmux add docs-update --no-hooks --no-file-ops --no-pane-cmds

# Skip just the file operations (e.g., you don't need node_modules)
workmux add quick-fix --no-file-ops
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/raine/workmux/blob/main/README.md

Demonstrates a typical sequence of workmux commands for managing a feature from creation to merging.

```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
```

--------------------------------

### Global Configuration Example

Source: https://github.com/raine/workmux/blob/main/README.md

Example of a global configuration file (`~/.config/workmux/config.yaml`). This sets personal defaults for all projects, including nerdfont icons, merge strategy, and default agent.

```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

```

--------------------------------

### Project Configuration Example

Source: https://github.com/raine/workmux/blob/main/README.md

Example of a project-specific configuration file (`.workmux.yaml`). This file overrides global settings for a particular project, defining custom post-create scripts, file symlinks, and panes.

```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

```

--------------------------------

### Automated Workmux Setup

Source: https://github.com/raine/workmux/blob/main/docs/guide/status-tracking.md

Run this command to automatically detect and install status tracking hooks for supported agent CLIs.

```bash
workmux setup
```

--------------------------------

### Preview what would be restored

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/resurrect.md

This example demonstrates how to preview the restoration process using the `--dry-run` flag.

```bash
# Preview what would be restored
workmux resurrect --dry-run
```

--------------------------------

### Install All Workmux Skills

Source: https://github.com/raine/workmux/blob/main/docs/guide/skills.md

Run this bash command to automatically install all supported agent skills for workmux. It detects installed agents and copies the necessary skills.

```bash
workmux setup --skills
```

--------------------------------

### Set Up Python Test Environment

Source: https://github.com/raine/workmux/blob/main/CONTRIBUTING.md

Create a virtual environment for Python tests, activate it, and install the required dependencies.

```bash
python -m venv tests/venv
source tests/venv/bin/activate
pip install -r tests/requirements.txt
```

--------------------------------

### Export Dockerfile for Sandbox Image

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sandbox.md

Creates a `Dockerfile.sandbox` in the current directory with the base system setup and agent-specific installation. Use the `--force` option to overwrite an existing Dockerfile.

```bash
workmux sandbox init-dockerfile [--force]
```

--------------------------------

### Install Development Binary

Source: https://github.com/raine/workmux/blob/main/CONTRIBUTING.md

Install the development binary for workmux, which symlinks to your Cargo bin directory.

```bash
just install-dev
```

--------------------------------

### Install development builds

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sandbox.md

Cross-compiles and installs workmux into containers and running Lima VMs.

```bash
workmux sandbox install-dev
```

```bash
workmux sandbox install-dev --release
```

```bash
workmux sandbox install-dev --skip-build
```

--------------------------------

### Build Zellij from Source

Source: https://github.com/raine/workmux/blob/main/docs/guide/zellij.md

Instructions to clone the Zellij repository, build it from source, and optionally install it to your PATH. This is required for the experimental Zellij backend.

```bash
git clone https://github.com/zellij-org/zellij.git
cd zellij
cargo build --release
# optionally install to PATH
cargo install --path .
```

--------------------------------

### Install llm-ollama for local models

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

Installs the llm-ollama integration to enable the use of local models with the llm CLI.

```bash
llm install llm-ollama
```

--------------------------------

### Example AI Agent Interaction with Workmux Docs

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/docs.md

This example shows how an AI agent can interpret the output of `workmux docs` to configure the workmux environment. The agent reads the documentation and then generates a `.workmux.yaml` file based on the instructions.

```bash
> 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
```

```yaml
Wrote 9 lines to .workmux.yaml
```

```yaml
- Left: claude agent (focused)
  - Right top: neovim
  - Right bottom: empty shell
```

--------------------------------

### Restore all worktrees

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/resurrect.md

This example shows the basic command to restore all worktrees that had agents running.

```bash
# Restore all worktrees that had agents running
workmux resurrect
```

--------------------------------

### Automating Pane Setup with Workmux

Source: https://github.com/raine/workmux/blob/main/docs/guide/configuration.md

Configure panes to automatically set up your development environment. Commands run immediately within tmux panes, allowing for parallel execution of tasks like dependency installation and agent initialization.

```yaml
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
```

--------------------------------

### Custom system prompt for branch name generation

Source: https://github.com/raine/workmux/blob/main/README.md

Defines a custom system prompt in `.workmux.yaml` to guide the LLM in generating branch names. This example specifies rules for format, length, and content, and provides examples of desired output.

```yaml
auto_name:
  model: 'gemini-2.5-flash-lite'
  background: true
  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.
```

--------------------------------

### Install workmux with Home Manager

Source: https://github.com/raine/workmux/blob/main/docs/guide/nix.md

Add the package to home.packages and define the configuration file using xdg.configFile.

```nix
{ inputs, pkgs, ... }:

{
  home.packages = [ inputs.workmux.packages.${pkgs.system}.default ];

  xdg.configFile."workmux/config.yaml".text = ''
    merge_strategy: rebase
    agent: claude
    panes:
      - command: <agent>
        focus: true
      - split: horizontal
  '';
}
```

--------------------------------

### Examples of sync-files command

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sync-files.md

Common usage patterns for syncing files to the current worktree or all worktrees.

```bash
# Sync files to the current worktree
workmux sync-files

# Sync files to all worktrees at once
workmux sync-files --all
```

--------------------------------

### Install Container Runtimes on macOS

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/container.md

Installs Docker Desktop, OrbStack, or Podman on macOS using Homebrew. Docker Desktop or OrbStack are recommended for a seamless experience.

```bash
# macOS
brew install --cask docker          # Docker Desktop
# or
brew install --cask orbstack        # OrbStack (Docker-compatible)
# or
brew install podman                 # Podman
```

--------------------------------

### Skip Setup Steps During Worktree Creation

Source: https://github.com/raine/workmux/blob/main/README.md

Skip specific setup steps like hooks or file operations during worktree creation using flags like --no-hooks and --no-file-ops.

```bash
# Skip expensive setup for documentation-only changes
workmux add docs-update --no-hooks --no-file-ops --no-pane-cmds
```

```bash
# Skip just the file operations (e.g., you don't need node_modules)
workmux add quick-fix --no-file-ops
```

--------------------------------

### Workmux Configuration Options

Source: https://github.com/raine/workmux/blob/main/skills/workmux/SKILL.md

Example configuration settings for Workmux, demonstrating agent selection, merge strategies, pane management, file copying/symlinking, and post-creation hooks.

```yaml
agent: claude                    # default agent for <agent> placeholder
```

```yaml
merge_strategy: rebase           # merge, rebase, or squash
```

```yaml
mode: window                     # window or session
```

```yaml
panes:
  - command: <agent>             # <agent> resolves to configured agent
    focus: true
  - split: horizontal            # second pane with shell
```

```yaml
files:
  copy:
    - .env                       # copy from main worktree
  symlink:
    - node_modules               # symlink from main worktree
```

```yaml
post_create:
  - '<global>'                   # include global hooks
  - npm install                  # project-specific setup
```

```yaml
base_branch: develop             # default base for new worktrees
```

```yaml
window_prefix: wm-               # tmux window name prefix
```

--------------------------------

### Confirm Agents Have Started

Source: https://github.com/raine/workmux/blob/main/skills/coordinator/SKILL.md

Verify that spawned agents have successfully started and are in a 'working' state before proceeding to wait for their completion. Use a timeout to prevent indefinite waiting.

```bash
workmux wait auth-module api-tests docs-update --status working --timeout 120
```

--------------------------------

### Install Prerequisites for Cross-Compilation

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/features.md

Before cross-compiling, ensure you have the necessary Rust target and cross-toolchain installed on your macOS host.

```bash
# First time: install prerequisites
rustup target add aarch64-unknown-linux-gnu
brew install messense/macos-cross-toolchains/aarch64-unknown-linux-gnu
```

--------------------------------

### Example Prompt with Skill Delegation

Source: https://github.com/raine/workmux/blob/main/skills/worktree/SKILL.md

This prompt format is used when instructing the agent to use a specific skill. It includes the task description and the skill invocation with any necessary flags.

```bash
[Task description here]

Use the skill: /skill-name [flags if any] [task description]
```

--------------------------------

### Install llm CLI

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

This command installs the llm CLI tool, which is used as a fallback for branch name generation if no agent or custom command is configured.

```bash
pipx install llm
```

--------------------------------

### Pi Manual Extension Installation

Source: https://github.com/raine/workmux/blob/main/docs/guide/status-tracking.md

Manually install the workmux status extension for Pi by downloading the extension file and placing it in the global extensions directory.

```bash
mkdir -p ~/.pi/agent/extensions
curl -o ~/.pi/agent/extensions/workmux-status.ts \
  https://raw.githubusercontent.com/raine/workmux/main/.pi/extensions/workmux-status.ts
```

--------------------------------

### Common configuration usage examples

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/config.md

Collection of common patterns for editing, path retrieval, and referencing the configuration.

```bash
# Edit global config
workmux config edit

# Use a specific editor
EDITOR=nano workmux config edit

# Print the config path (for use in scripts)
cat "$(workmux config path)"

# Print the default config reference
workmux config reference
```

--------------------------------

### Example output of workmux list

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/list.md

A sample representation of the command output showing branch, age, agent, multiplexer, and merge status.

```text
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
```

--------------------------------

### Start New Task with Inline Prompt

Source: https://github.com/raine/workmux/blob/main/docs/guide/workflows.md

Provide the task prompt directly on the command line when starting a new worktree with automatic branch naming.

```bash
workmux add -A -p "Add pagination to the /users endpoint"
```

--------------------------------

### Start New Task with Prompt from File

Source: https://github.com/raine/workmux/blob/main/docs/guide/workflows.md

Specify a file containing the task prompt when initiating a new worktree with automatic branch naming.

```bash
workmux add -A -P task-spec.md
```

--------------------------------

### CLI: sandbox shell

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sandbox.md

Starts an interactive shell in a sandbox environment.

```APIDOC
## CLI: workmux sandbox shell

### Description
Starts an interactive shell using the same mounts and environment as a normal worktree sandbox.

### Method
CLI Command

### Endpoint
workmux sandbox shell [command...]

### Parameters
#### Path Parameters
- **command** (string) - Optional - Specific command to run instead of bash
```

--------------------------------

### Manual git worktree and tmux setup

Source: https://github.com/raine/workmux/blob/main/docs/guide/index.md

The multi-step manual process required to create and clean up a git worktree and tmux environment without automation.

```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
```

--------------------------------

### Dashboard configuration and filtering examples

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/dashboard.md

Various command-line flags to customize the dashboard layout, filter sessions, or navigate directly to specific views.

```bash
# Open dashboard with default layout
workmux dashboard

# Open with smaller preview pane (40% of height)
workmux dashboard --preview-size 40

# Open diff view directly for current worktree
workmux dashboard --diff

# Show only agents in the current tmux session
workmux dashboard --session

# Open directly on the Worktrees tab
workmux dashboard --tab worktrees
```

--------------------------------

### Install sccache for Rust Projects

Source: https://github.com/raine/workmux/blob/main/README.md

Install sccache using Homebrew to enable global caching of compiled Rust dependencies, improving build times across worktrees.

```bash
brew install sccache
```

--------------------------------

### Start Interactive Shell in Sandbox

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sandbox.md

Starts an interactive shell within a sandbox, using the same mounts and environment as a normal worktree sandbox. It supports both container and Lima backends. You can run a specific command instead of the default shell by appending it after `--`.

```bash
# Start a new shell (container backend starts a new container, Lima connects to existing VM)
workmux sandbox shell

# Run a specific command instead of bash
workmux sandbox shell -- <command...>
```

--------------------------------

### Start New Task with Auto-Named Branch

Source: https://github.com/raine/workmux/blob/main/docs/guide/workflows.md

Use this command to start a new task from scratch. It automatically generates a branch name from your prompt and passes the prompt to the agent. Requires the `llm` CLI tool.

```bash
workmux add -A
```

--------------------------------

### Parallel AI workflow example

Source: https://github.com/raine/workmux/blob/main/docs/guide/quick-start.md

Initiate multiple AI agents working on different tasks simultaneously, each in its own isolated worktree. This avoids conflicts and simplifies branch management.

```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
```

--------------------------------

### Direnv Configuration for Environment Loading

Source: https://github.com/raine/workmux/blob/main/docs/guide/monorepos.md

This example shows how to configure direnv using an .envrc file to automatically load environment variables from .env and conditionally from .env.local, ensuring that .env.local overrides .env when it exists.

```bash
# .envrc
dotenv
dotenv_if_exists .env.local
```

--------------------------------

### Claude Prune Output

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/claude.md

Example output showing the removal of stale paths and the creation of a backup file.

```text
  - Removing: /Users/user/project__worktrees/old-feature

✓ Created backup at ~/.claude.json.bak
✓ Removed 3 stale entries from ~/.claude.json
```

--------------------------------

### Generate Shell Completion Script

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/completions.md

Use this command to generate a completion script for your shell. Specify the shell type (bash, zsh, or fish) as an argument. Refer to the installation guide for setup instructions.

```bash
workmux completions <shell>
```

```bash
# Generate completions for zsh
workmux completions zsh
```

--------------------------------

### Add Cursor-Based Pagination

Source: https://github.com/raine/workmux/blob/main/docs/index.md

Use the 'workmux add' command to create a branch, worktree, and start an agent with a specific prompt.

```bash
workmux add -A "Add cursor-based pagination to /api/users"
```

--------------------------------

### Use workmux via Mise

Source: https://github.com/raine/workmux/blob/main/docs/guide/installation.md

Installs and manages workmux using the 'mise' version manager.

```bash
mise use -g cargo:raine/workmux
```

--------------------------------

### Open Worktree and Re-run Dependency Installation

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/open.md

Opens the worktree and automatically triggers the re-installation of dependencies using defined hooks.

```bash
workmux open user-auth --run-hooks
```

--------------------------------

### Custom Provisioning Script for Lima VM

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/lima.md

This script demonstrates how to add custom provisioning steps to a Lima VM. It installs additional CLI tools like ripgrep, fd-find, and jq, and sets up Node.js using nvm.

```yaml
sandbox:
  backend: lima
  lima:
    provision: |
      # Install extra CLI tools
      sudo apt-get install -y ripgrep fd-find jq

      # Install Node.js via nvm
      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
      export NVM_DIR="$HOME/.nvm"
      . "$NVM_DIR/nvm.sh"
      nvm install 22
```

--------------------------------

### Display configuration reference

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/config.md

Prints the default configuration file content including all documented options.

```bash
workmux config reference
```

--------------------------------

### Install Copilot CLI Workmux Status Hooks

Source: https://github.com/raine/workmux/blob/main/docs/guide/status-tracking.md

Manually copy the hooks configuration to your repository to enable Workmux status tracking with Copilot CLI. This setup tracks 'working' and 'done' states.

```bash
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
```

--------------------------------

### Install workmux via Cargo

Source: https://github.com/raine/workmux/blob/main/docs/guide/installation.md

Installs workmux using Cargo, the Rust package manager. Requires Rust to be installed.

```bash
cargo install workmux
```

--------------------------------

### Example Workmux Add Command

Source: https://github.com/raine/workmux/blob/main/skills/worktree/SKILL.md

This command adds a new worktree with a specified name, using a temporary file for the prompt. The `-b` flag indicates a new branch, and `-P` specifies the prompt file.

```bash
workmux add <worktree-name> -b -P <temp-file>
```

--------------------------------

### Install workmux

Source: https://github.com/raine/workmux/blob/main/docs/guide/quick-start.md

Install workmux using the provided curl script. Ensure you have a compatible terminal multiplexer like tmux installed.

```bash
curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash
```

--------------------------------

### Lima Configuration with Custom Provisioning Script

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/lima.md

This configuration allows for custom provisioning scripts to run on a VM, even when default provisioning is skipped. It's useful for layering additional setup on top of a pre-built image.

```yaml
sandbox:
  backend: lima
  lima:
    provision: |
      sudo apt-get install -y ripgrep fd-find jq
```

--------------------------------

### Example Nested Config

Source: https://github.com/raine/workmux/blob/main/docs/guide/monorepos.md

This YAML configuration demonstrates how to set up a nested .workmux.yaml file for a specific project within a monorepo. It specifies an agent and defines file operations and post-creation hooks relative to the config directory.

```yaml
# backend/.workmux.yaml
agent: claude

files:
  copy:
    - .env # Copies backend/.env to worktree's backend/.env

post_create:
  - cargo build # Runs in worktree's backend/ directory
```

--------------------------------

### Manual Workflow Without Workmux

Source: https://github.com/raine/workmux/blob/main/README.md

Illustrates the multi-step manual process for creating a worktree, setting up tmux, and cleaning up, which workmux simplifies.

```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'	mux 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
```

--------------------------------

### Run Package Manager Install in Background with Workmux Panes

Source: https://github.com/raine/workmux/blob/main/docs/guide/git-worktree-caveats.md

Configure Workmux panes to run commands like 'npm install' after worktree creation. This installs dependencies in the background without blocking worktree and window creation.

```yaml
panes:
  - command: npm install
    focus: true
  - split: horizontal
```

--------------------------------

### Execute project release

Source: https://github.com/raine/workmux/blob/main/RELEASE.md

Run the release command to bump versions, generate changelogs, and publish.

```bash
just release-patch  # or release-minor, release-major
```

--------------------------------

### Install workmux via Homebrew

Source: https://github.com/raine/workmux/blob/main/docs/guide/installation.md

Installs workmux using the Homebrew package manager on macOS and Linux systems.

```bash
brew install raine/workmux/workmux
```

--------------------------------

### Install workmux via Nix

Source: https://github.com/raine/workmux/blob/main/docs/guide/installation.md

Installs workmux using the Nix package manager. Requires Nix with flakes enabled.

```bash
nix profile install github:raine/workmux
```

--------------------------------

### Print Default Configuration

Source: https://github.com/raine/workmux/blob/main/README.md

Prints the default configuration file, useful for discovering options or providing context to AI agents.

```bash
workmux config reference
```

--------------------------------

### Claude Code Manual Plugin Installation

Source: https://github.com/raine/workmux/blob/main/docs/guide/status-tracking.md

Manually install the workmux status plugin for Claude Code via its plugin marketplace.

```bash
claude plugin marketplace add raine/workmux
claude plugin install workmux-status
```

--------------------------------

### Basic workmux add usage

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

Demonstrates creating new worktrees from local or remote branches, with options for background creation, custom directory names, and custom window names.

```bash
# Create a new branch and worktree
workmux add user-auth

# Use an existing branch
workmux add existing-work

# Create a new branch from a specific base
workmux add hotfix --base production

# Create a worktree from a remote branch (creates local branch "user-auth-pr")
workmux add origin/user-auth-pr

# Remote branches with slashes work too (creates local branch "feature/foo")
workmux add origin/feature/foo

# 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 default tmux target
workmux add feature/long-descriptive-branch-name --name short

# Use a custom window name while keeping the branch-derived worktree path
workmux add feature/long-descriptive-branch-name --target-name review-short

# Create a custom-named window inside an existing PR review session
workmux add feature/review --parent-session prs --target-name review-123

# Open existing worktree if it exists, create if it doesn't (idempotent)
workmux add my-feature -o
```

--------------------------------

### Build Default Sandbox Image Locally

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/container.md

Build the default sandbox container image locally instead of pulling it from a registry.

```bash
workmux sandbox build
```

--------------------------------

### Simplified Workflow With Workmux

Source: https://github.com/raine/workmux/blob/main/README.md

Shows the concise workmux commands to achieve the same outcome as the manual workflow.

```bash
# Create the environment
workmux add user-auth

# ... work on the feature ...

# Merge and clean up
workmux merge
```

--------------------------------

### Cross-Compile and Install Local Workmux Build

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/features.md

Use this command to cross-compile and install your local Workmux development build into containers or running VMs. Re-run after code changes.

```bash
# Cross-compile and install into containers and running VMs
workmux sandbox install-dev
```

```bash
# After code changes, rebuild and reinstall
workmux sandbox install-dev
```

```bash
# Use --release for optimized builds
workmux sandbox install-dev --release
```

```bash
# Skip rebuild if binary hasn't changed
workmux sandbox install-dev --skip-build
```

--------------------------------

### CLI: sandbox init-dockerfile

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sandbox.md

Exports a customizable Dockerfile for building a custom sandbox image.

```APIDOC
## CLI: workmux sandbox init-dockerfile

### Description
Creates a Dockerfile.sandbox in the current directory with the base system setup.

### Method
CLI Command

### Endpoint
workmux sandbox init-dockerfile

### Parameters
#### Query Parameters
- **--force** (flag) - Optional - Overwrite existing Dockerfile
```

--------------------------------

### Start Interactive Shell in Sandbox Container

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/container.md

Use this command to start a new interactive shell within a Workmux sandbox container with the same mounts as a regular agent run.

```bash
# Start a new container with the same mounts
workmux sandbox shell
```

--------------------------------

### Upgrade Workmux via Homebrew

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/update.md

If workmux was installed using Homebrew, use this command to upgrade it. The update command will detect Homebrew installations and prompt you to use this command instead.

```bash
brew upgrade workmux
```

--------------------------------

### Build Custom Sandbox Docker Image

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/container.md

Use this command sequence to initialize, customize, and build a Dockerfile for a custom sandbox environment.

```bash
workmux sandbox init-dockerfile        # creates Dockerfile.sandbox
vim Dockerfile.sandbox                 # customize
docker build -t my-sandbox -f Dockerfile.sandbox .
```

--------------------------------

### Initialize workmux configuration

Source: https://github.com/raine/workmux/blob/main/docs/guide/quick-start.md

Optionally, initialize the workmux configuration to create a `.workmux.yaml` file for customizing workflows. workmux functions with default settings if this step is skipped.

```bash
workmux init
```

--------------------------------

### Install Workmux Status Extension for Oh My Pi

Source: https://github.com/raine/workmux/blob/main/docs/guide/status-tracking.md

Manually install the Workmux status extension by downloading the TypeScript file to the global OMP extensions directory. Restart OMP for the changes to apply.

```bash
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
```

--------------------------------

### Create a worktree

Source: https://github.com/raine/workmux/blob/main/skills/workmux/SKILL.md

Creates a git worktree, sets up file operations and hooks, and initializes a tmux window. Use flags to customize behavior like background creation, prompt handling, and branch management.

```bash
workmux add <branch-name>
```

--------------------------------

### Install Workmux Status Plugin for OpenCode

Source: https://github.com/raine/workmux/blob/main/docs/guide/status-tracking.md

Manually install the Workmux status plugin by downloading the package.json and TypeScript file to the global OpenCode plugin directory. Restart OpenCode for the plugin to take effect.

```bash
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
```

--------------------------------

### Enable Container Backend

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/index.md

Configuration to enable the default container sandbox backend.

```yaml
# ~/.config/workmux/config.yaml or .workmux.yaml
sandbox:
  enabled: true
```

--------------------------------

### Uninstall workmux via Cargo

Source: https://github.com/raine/workmux/blob/main/docs/guide/installation.md

Uninstalls workmux when it was installed using Cargo.

```bash
cargo uninstall workmux
```

--------------------------------

### Install workmux on NixOS

Source: https://github.com/raine/workmux/blob/main/docs/guide/nix.md

Add the workmux package to the system-wide environment packages.

```nix
{ inputs, pkgs, ... }:

{
  environment.systemPackages = [
    inputs.workmux.packages.${pkgs.system}.default
  ];
}
```

--------------------------------

### Uninstall workmux via Homebrew

Source: https://github.com/raine/workmux/blob/main/docs/guide/installation.md

Uninstalls workmux and untaps the repository when installed via Homebrew.

```bash
brew uninstall workmux
brew untap raine/workmux
```

--------------------------------

### Print configuration path

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/config.md

Outputs the absolute path to the global configuration file, suitable for use in shell scripts.

```bash
workmux config path
# Output: /home/user/.config/workmux/config.yaml
```

--------------------------------

### Create worktrees for multiple agents with a focused prompt

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

Create worktrees for specified agents using the `-a` flag and provide a focused prompt using `-p`.

```bash
# 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
```

--------------------------------

### Configure llm CLI with OpenAI keys

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

Sets up the llm CLI to use OpenAI models by configuring API keys.

```bash
llm keys set openai
```

--------------------------------

### Copy File to Worktree Directory

Source: https://github.com/raine/workmux/blob/main/README.md

Shows how to copy a configuration file into a specific worktree's directory using command substitution with 'workmux path'.

```bash
cp config.json "$(workmux path feature-branch)/"
```

--------------------------------

### Rename Worktree Examples

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/rename.md

Common usage patterns for renaming worktrees, including local and branch-specific renames.

```bash
# 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
```

--------------------------------

### Sandbox with Podman and Custom Environment

Source: https://github.com/raine/workmux/blob/main/docs/guide/sandbox/container.md

Configures the sandbox to use a custom image, pass specific environment variables, and set custom environment variables. Uses Podman as the container runtime.

```yaml
sandbox:
  enabled: true
  image: my-sandbox:latest
  env_passthrough:
    - GITHUB_TOKEN
    - ANTHROPIC_API_KEY
  env:
    GH_TOKEN: ghp_xxxxxxxxxxxx
  container:
    runtime: podman
```

--------------------------------

### Create Temporary File for Prompt

Source: https://github.com/raine/workmux/blob/main/skills/worktree/SKILL.md

This snippet demonstrates how to create a temporary markdown file and write prompt content into it using a heredoc. Note the path of the temporary file for subsequent steps.

```bash
tmpfile=$(mktemp).md
cat > "$tmpfile" << 'EOF'
Implement feature X...
EOF
echo "$tmpfile"  # Note the path for step 2
```

--------------------------------

### Add worktree with prompt from file

Source: https://github.com/raine/workmux/blob/main/docs/guide/agents.md

Use this command to create a new worktree and provide a prompt for an AI agent from a specified file.

```bash
workmux add feature/refactor --prompt-file task-description.md
```

--------------------------------

### Open Dashboard on Specific Tab

Source: https://github.com/raine/workmux/blob/main/README.md

Starts the workmux dashboard and immediately focuses on either the 'agents' or 'worktrees' tab.

```bash
workmux dashboard -t agents
```

--------------------------------

### Open or Switch to Existing Worktree Window

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/open.md

Use this command to open a new window for a worktree or switch to an existing one. This is the most basic usage of the 'open' command.

```bash
workmux open user-auth
```

--------------------------------

### Run command in sandbox

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/sandbox.md

Internal command used by pane setup to execute processes within a Lima VM.

```bash
workmux sandbox run <worktree> -- <command...>
```

--------------------------------

### Pipe stdin to create worktrees with a prompt file

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/add.md

Create worktrees by piping input from stdin and using a prompt file for agent instructions. Branch names can be LLM-generated.

```bash
# 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
```

--------------------------------

### Run workmux without installation

Source: https://github.com/raine/workmux/blob/main/docs/guide/nix.md

Execute workmux directly using nix run without adding it to the system profile.

```bash
nix run github:raine/workmux -- --help
```

--------------------------------

### Display README with terminal formatting

Source: https://github.com/raine/workmux/blob/main/README.md

Displays the README with terminal formatting for quick reference. When piped, it outputs raw markdown.

```bash
workmux docs
```

--------------------------------

### Examples of workmux list usage

Source: https://github.com/raine/workmux/blob/main/docs/reference/commands/list.md

Common usage patterns including filtering, PR status display, and JSON output.

```bash
# List all worktrees
workmux list

# List with PR status
workmux list --pr

# Output as JSON for scripting
workmux list --json

# Filter to a specific worktree
workmux list my-feature

# Filter to multiple worktrees
workmux list feature-auth feature-api
```