DOCSEARCHbyAlgolia
Submit Docs

workmux

repository·main·Indexed 23 days ago

https://github.com/raine/workmux

An opinionated workflow tool (v0.1.232) that orchestrates git worktrees and terminal multiplexers like tmux, Zellij, Kitty, or WezTerm to enable parallel development environments. It is specifically designed to support running multiple AI agents simultaneously by providing isolated workspaces, automated pane layouts, and lifecycle hooks for environment setup and cleanup.

Tokens
96.6K
Snippets
272
Records
476
Agent score
80%

What's inside workmux

  1. What is workmux?

    main

    workmux is a workflow tool designed to manage git worktrees and terminal multiplexer windows (like tmux, kitty, WezTerm, or Zellij) as isolated development environments. It is specifically optimized for running multiple AI agents in parallel by providing each task with its own directory, terminal state, editor session, and dev server.

    Instead of manually managing branches and windows, workmux orchestrates the creation, configuration, and cleanup of these environments through a single command interface.

  2. Core features of workmux

    main

    workmux provides several automation features for managing parallel development:

    • Automated Environment Creation: The add command creates git worktrees paired with matching tmux/kitty/WezTerm/Zellij windows/tabs.
    • Lifecycle Management: The merge command handles the full cleanup (merging branches, deleting worktrees, closing windows).
    • Automated Setup: Supports running post-creation hooks (e.g., npm install), copying configuration files (like .env), and symlinking dependencies (like node_modules).
    • Layout Management: Automatically sets up preferred tmux pane layouts (editor, shell, watchers, etc.).
    • AI Agent Integration:
      • Supports delegating tasks via the /worktree skill.
      • Can display Claude agent status in tmux window names.
      • Features automatic branch name generation from prompts using LLMs.
    • Monitoring: Includes a Dashboard for monitoring agents and reviewing changes.
    • Security: Supports sandboxing agents in containers or VMs.

  3. What is workmux and how does it work?

    main

    workmux is a workflow tool designed for parallel development. It uses git worktrees to provide isolated file system environments and terminal multiplexers (primarily tmux, but also Zellij, Kitty, and WezTerm) to provide isolated terminal sessions.

    Core Mental Model

    Instead of switching branches in a single directory (which requires stashing or committing unfinished work), you create a new "worktree" for every task. Each worktree is paired with a dedicated tmux window. This allows you to:

    • Run multiple AI agents in parallel without context conflicts.
    • Maintain separate dev servers, editor sessions, and terminal states for different features.
    • Switch between tasks simply by switching tmux tabs/windows.

    Key Features

    • Automated Setup: Automatically handles .env files, node_modules symlinking, and dependency installation.
    • Lifecycle Management: workmux add creates the environment; workmux merge or workmux remove cleans it up.
    • Customizable Layouts: Automatically sets up preferred tmux pane layouts (editor, shell, watchers, etc.).
    • Agent Integration: Includes a Dashboard for monitoring agents and a Sidebar for a persistent view of all active agents across windows.

  4. How workmux configuration works

    main

    workmux uses a two-level configuration system to manage settings across different scopes:

    1. Global Configuration: Located at ~/.config/workmux/config.yaml. This defines personal defaults applied to all projects.
    2. Project Configuration: Located at .workmux.yaml in your project root. This defines project-specific overrides.

    Key Behaviors:

    • Overrides: Project settings always override global settings.
    • Nesting: When running workmux from a subdirectory, it walks upward to find the nearest .workmux.yaml, supporting nested configurations for monorepos.
    • Merging vs. Replacing:
      • For post_create and file operation lists (files.copy, files.symlink), you can use the "<global>" keyword to include global values alongside project-specific ones.
      • Other settings, such as panes, are replaced entirely when defined in a project config.
    ### Global configuration example
`~/.config/workmux/config.yaml`:

```yaml
nerdfont: true # Enable nerdfont icons (prompted on first run)
merge_strategy: rebase # Make workmux merge do rebase by default
merge_keep: true # Keep worktree, window, and branch after merge by default
agent: claude

panes:
  - command: <agent> # Start the configured agent (e.g., claude)
    focus: true
  - split: horizontal # Second pane with default shell

    Project configuration example

    .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

  5. Understand the RPC protocol for sandbox communication

    main

    The supervisor (host) and guest (sandbox) communicate using JSON-lines over TCP. Each request is a single JSON object on one line. Requests are authenticated using a per-session token provided via the WM_RPC_TOKEN environment variable.

    Supported RPC requests:

    • SetStatus: Updates the tmux pane status icon (working/waiting/done/clear).
    • SetTitle: Renames the tmux window.
    • Heartbeat: A health check that returns Ok.
    • SpawnAgent: Triggers workmux add on the host to create a new worktree and pane.
    • Exec: Runs a command on the host and streams stdout/stderr back (used by host-exec shims like afplay).
    • Merge: Runs workmux merge on the host with all flags forwarded.
    • ClipboardRead: Reads the host clipboard and writes image data to the shared worktree filesystem (used by wl-paste/xclip shims).

  6. How Worktree Agent Coordination works

    main

    A Worktree agent is a Claude Code session running in its own dedicated git worktree and branch. A Handle is the unique worktree directory name used to address these agents in all workmux commands.

    Agents run in background tmux windows, meaning you interact with them exclusively via the CLI. They transition through several automatic Statuses:

    • working: The agent is currently processing a task.
    • waiting: The agent requires user input.
    • done: The agent has finished its task.

    Cross-project targeting: Agent commands like send, capture, status, wait, and run can target agents in other projects. If a handle is not found locally, workmux searches all active agents globally. Use the project:handle syntax to disambiguate if names collide across different projects.

  7. How sandboxing works in workmux

    main

    workmux provides sandboxing to isolate agents from host secrets (like SSH keys, AWS credentials, and GPG keys) while allowing them to work on your code. When a sandbox is enabled, agents have read-write access to:

    • The current worktree directory
    • The main worktree directory (for symlink resolution)
    • The shared .git directory (for git operations)
    • Agent settings and credentials

    A built-in RPC bridge ensures that host-side workmux features (like status indicators, the dashboard, spawning/merging agents, and image pasting) remain synchronized with the agent's activity inside the sandbox.

  8. Understand the host-exec security model

    main

    When using host_commands, workmux applies several layers of defense to limit the impact of a compromised agent:

    • Allowed commands: Only commands explicitly listed in host_commands (or built-ins) can be executed.
    • Strict command names: Command names must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ (no path separators or shell metacharacters).
    • No shell injection: Arguments are passed as positional parameters to bash ("$@") rather than being interpolated into a shell string. If toolchain wrapping is active, it uses Devbox/Nix; otherwise, it executes directly via the OS.
    • Environment isolation: Child processes run with a sanitized environment. Only essential variables (PATH, HOME, TERM, etc.) are passed. Host secrets (API keys) are not inherited.
    • Filesystem sandbox:
      • macOS: Uses sandbox-exec (Seatbelt) to deny access to sensitive directories (e.g., ~/.ssh, ~/.aws, keychains) and restricts writes to $HOME except for toolchain caches (.cache, .cargo, etc.).
      • Linux: Uses bwrap (Bubblewrap) to provide a read-only root filesystem and isolation. Note: bwrap must be installed (apt install bubblewrap) or host-exec commands will be refused.
    • Global-only configuration: host_commands and rpc_host can only be set in the global config to prevent malicious projects from hijacking execution.
    • Worktree-locked: All commands execute with the project worktree as the working directory.

    Note on bypassing security: Setting sandbox.dangerously_allow_unsandboxed_host_exec: true in your global config skips the filesystem sandbox entirely.

  9. Enable agent sandboxing

    main

    Workmux can run agents inside isolated environments (Docker/Podman/Apple Container or Lima VMs) to protect your host machine. Agents are restricted to the project worktree and cannot access sensitive host files like SSH keys or AWS credentials.

    Configuration

    Enable sandboxing in ~/.config/workmux/config.yaml or .workmux.yaml:

    sandbox:
  enabled: true
  # backend: lima  # uncomment for Lima VMs (default: container)

    Backend Comparison

    • Container (Default): Uses Docker, Podman, or Apple Container. It is ephemeral (new container per session) and provides process/VM-level isolation. It supports network restrictions via a domain allowlist.
    • Lima VM: Uses Lima VMs for machine-level isolation. It is persistent (stateful VMs) and includes built-in Nix and Devbox support.

  10. How the sidebar works and its lifecycle

    main

    The sidebar is powered by a background daemon that polls tmux state every 2 seconds and pushes snapshots to sidebar panes via a Unix socket.

    • Automatic Creation: The sidebar creates a tmux pane on the configured edge of every existing window. It uses a tmux hook (after-new-window) to ensure new windows automatically receive a sidebar.
    • Disabling: Running workmux sidebar while the sidebar is active disables it globally, killing all sidebar panes, the daemon, and removing the hooks.
    • Session Scoping: Using workmux sidebar --session allows you to manage sidebars for specific sessions independently. Starting a global sidebar will replace any existing session-scoped sidebars.

  11. Compare Container vs Lima VM sandboxing backends

    main

    workmux supports two sandboxing backends. Choose based on your isolation and persistence requirements:

    Container (Docker/Podman/Apple Container)

    • Best for: Simple, ephemeral sessions where no state should accumulate.
    • Isolation: Process-level (namespaces) or VM-level (Apple Container on macOS).
    • Persistence: Ephemeral (new container per session).
    • Toolchain: Use a custom Dockerfile or proxy commands to the host.
    • Network: Supports optional domain-based restrictions.
    • Platform: macOS, Linux.

    Lima VM

    • Best for: Persistent environments with complex toolchain requirements.
    • Isolation: Machine-level (virtual machine).
    • Persistence: Persistent (stateful VMs).
    • Toolchain: Built-in Nix & Devbox support, custom provisioning via shell scripts.
    • Network: Unrestricted.
    • Platform: macOS, Linux.

  12. Automating worktree lifecycle and setup

    main

    workmux solves common git worktree pain points by automating setup and cleanup:

    • Setup: Unlike manual worktrees which are clean checkouts (missing .env, node_modules, etc.), workmux can copy configuration files, symlink dependencies, and run setup commands automatically upon creation.
    • Cleanup: The workmux merge command automates the full lifecycle: merging the branch, deleting the worktree, closing the associated tmux window, and removing the local branch.
    • Conflict Resolution: The /merge skill allows agents to autonomously rebase onto a base branch, review upstream changes, and resolve conflicts by understanding both sides of the change.