raine / workmux

Parallel development in tmux* with git worktrees 📖 Documentation · Install · Quick start · Commands · Changelog --- Giga opinionated zero-friction workflow tool for managing git worktrees 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 orchestrates the rest. \* Also supports kitty , WezTerm , and Zellij as alternative backends. 📚 See the full documentation for guides and configuration reference. 📖 **New to workmux?** Read the introduction blog post for a quick overview. Why workmux? **Parallel workflows.** Work on multiple features or hotfixes at 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 , no , no dev server). workmux can copy config files, symlink dependencies, and run install commands on creation. **One-command cleanup.** 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? Features • Create git worktrees with matching tmux windows in a single command ( ) • Merge branches and clean up everything (worktree, tmux window, branches) in one command ( ) • Dashboard for monitoring agents, reviewing changes, and sending commands • Delegate tasks to worktree agents with the skill • Display Claude agent status in tmux window names • 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 ( , ) into new worktrees • Sandbox agents in containers or VMs for enhanced security • Automatic branch name generation from prompts using LLM • Shell completions Hype > "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 🔗 Installation Bash YOLO Homebrew (macOS/Linux) Cargo Requires Rust. Install via rustup if you don't have it. Nix See Nix guide for flake and home-manager setup. --- For manual installation, see pre-built binaries. Quick start > [!NOTE] > workmux requires a terminal multiplexer. Make sure you have > tmux (or > WezTerm / > Kitty / > Zellij) installed and running > before you start. See My tmux setup > if you need a starting point. • **Initialize configuration (optional)**: This creates a 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**: This will: • Create a git worktree at • Copy config files and symlink dependencies (if configured) • Run any setup commands • Create a tmux window named (the prefix is configurable) • Set up your configured or the default tmux pane layout • Automatically switch your tmux client to the new window • **Do your thing** • **Finish and clean up** **Local merge:** Run to merge into the base branch and clean up in one step. **PR workflow:** Push and open a PR. After it's merged, run to clean up. Configuration workmux uses a two-level configuration system: • **Global** ( ): Personal defaults for all projects • **Project** ( ): Project-specific overrides Project settings override global settings. When you run workmux from a subdirectory, it walks upward to find the nearest , allowing nested configs for monorepos. See the Monorepos guide for details. For and file operation lists ( , ), you can use to include global values alongside project-specific ones. Other settings like are replaced entirely when defined in the project config. Global configuration example : Project configuration example : For a real-world example, see workmux's own . Configuration options Most options have sensible defaults. You only need to configure what you want to customize. Basic options | Option | Description | Default | | ---------------- | ---------------------------------------------------- | ----------------------- | | | Branch to merge into | Auto-detected | | | Default base branch for new worktrees | Current branch | | | Directory for worktrees (absolute or relative) | | | | Prefix for tmux window/session names | | | | Tmux mode ( or ) | | | | Default agent for placeholder | | | | Default merge strategy ( , , ) | | | | Dashboard color theme ( , ) | | Naming options | Option | Description | Default | | ----------------- | ------------------------------------------- | ------- | | | How to derive names from branches | | | | Prefix for worktree directories and windows | none | strategies: • : Use the full branch name (slashes become dashes) • : Use only the part after the last (e.g., → ) Panes Define your tmux pane layout with the array. For multiple windows in session mode, use instead (they are mutually exclusive). Each pane supports: | Option | Description | Default | | ------------ | -------------------------------------------------------------- | ------- | | | Command to run (see agent placeholders) | Shell | | | Whether this pane receives focus | | | | Split direction ( or ) | — | | | Absolute s…