workmux: git worktrees and tmux windows as one parallel dev environment

The collision workmux is built to remove

Running two features at once in one checkout means stashing, switching branches, and restarting whatever dev server the other branch was holding. git worktree already solves the filesystem half of that: each branch gets its own directory. What it does not solve is the human half. A second directory is a second terminal to open, a second set of panes to arrange, a second thing to remember to delete.

workmux targets that gap. The README describes it as an "opinionated workflow tool that orchestrates git worktrees and tmux", and the unit of work is one window per task: its own terminal state, editor session, dev server, and AI agent. The stated audience is developers running multiple coding agents in parallel, which is why the README leads with "Perfect for running multiple AI agents in parallel without conflict." If you run one branch at a time, the tool has nothing to coordinate.

How add and merge map worktrees onto tmux windows

The mechanism is deliberately thin. workmux does not replace git or tmux; it calls them. `add` creates a git worktree and a matching tmux window in one step. `merge` runs the full teardown: merge the branch, delete the worktree, close the tmux window, remove the local branch. Between those two commands, workmux is mostly a naming and setup layer.

The README states the default worktree location as `<project_root>/../<project_name>__worktrees/new-feature`, so worktrees sit as siblings of the repository rather than inside it. New worktrees start broken by design, and the README is explicit about that: no `.env`, no `node_modules`, no dev server. Configuration handles it. workmux can copy config files, symlink dependencies, and run install commands on creation, and it can set up a preferred tmux pane layout. The project also ships a dashboard for monitoring agents and a sidebar for a persistent view across windows, plus agent status shown in tmux window names. The backend is not hardcoded: the README lists kitty, WezTerm, and Zellij as alternatives to tmux.

Installing workmux and creating a first worktree

workmux is distributed as pre-built binaries and through several package managers. Homebrew is the shortest path on macOS and Linux:

brew install raine/workmux/workmux

Cargo works if you already have rustup, and there is a curl installer the README labels "Bash YOLO":

cargo install workmux

Before the first command, the README is unambiguous: a terminal multiplexer must be installed and running. workmux does not start tmux for you. Configuration is optional because defaults exist, but generating the file is how you discover what is tunable:

workmux init

That writes a `.workmux.yaml` at the project root for pane layouts, setup commands, and file operations. Then the actual first use:

workmux add new-feature

According to the README, this creates the worktree at `<project_root>/../<project_name>__worktrees/new-feature`, copies config files, symlinks dependencies, and opens the corresponding tmux window. What you should see is a new window in your existing tmux session, not a new terminal application. Cleanup is the mirror command, `workmux merge`, which merges the branch and removes the worktree, window, and local branch together.

Where the opinionated design pushes back

The strongest constraint is the dependency itself. workmux assumes you already have tmux, WezTerm, Kitty, or Zellij configured and running. The README points readers to a separate blog post on tmux setup if they need a starting point, which is a fair signal that the prerequisite is not trivial for newcomers. If your team opens terminals from an IDE and never touches a multiplexer, workmux is the wrong tool, and the README says so indirectly by recommending tmux as worth picking up.

The second constraint is the directory convention. Worktrees are created as siblings of the project root, outside the repository. That is a real choice with consequences: tooling that assumes everything lives under the repo, or that globs the project directory for source files, will not see the worktrees. The README does not document a rollback path for a partially completed `add`, and it does not describe what happens if the tmux window is closed manually while the worktree remains. The `merge` command is described as handling the full lifecycle, which implies the components are tracked together, but the failure semantics of breaking that pairing are not spelled out in the README.

The version number is also worth reading literally. Cargo.toml pins the package at 0.1.266, and the release history shows builds arriving within hours of each other on 2026-09-21 and 2026-09-22. Frequent patch releases at a 0.1 version mean the surface is still moving. The last push to the repository was on 2026-09-22.

workmux vs worktrunk, Herdr, and plain tmux

The comparison people search for most is against plain tmux, and the honest answer is that workmux is a layer on top of it rather than a replacement. Plain tmux gives you windows and panes but knows nothing about branches; you would create the worktree yourself with `git worktree add`, then open a window, then arrange panes, then remember to clean up both. workmux collapses those steps into `add` and `merge` and keeps the pairing in its own state.

Against worktrunk, the searches suggest the two are compared directly, but the README does not describe worktrunk's approach, so any difference I state would be invented. The same applies to Herdr. What can be said from the README is narrower: one quoted user argues workmux is preferable because it "adds busy/question/done status, manages worktrees by itself" and "lives on an already existing tmux setup." That is a user's framing, not a specification. The real design difference to weigh is whether you want worktree lifecycle management bundled with window management at all. A tool that only manages worktrees leaves your multiplexer untouched; workmux deliberately couples the two, which is exactly why its teardown is one command and exactly why its failure modes span both systems.

Maintenance, releases, and the MIT licence

The repository is not archived, and the last push was on 2026-09-22, with release v0.1.266 published the same day. The project is maintained by a small group, with Cargo.toml listing "workmux contributors" as the author. Release cadence is high but each release is a patch bump at 0.1, so upgrading is unlikely to be a major-version migration event, though nothing in the README guarantees API stability before 1.0.

The licence is MIT, which permits commercial and private use, modification, and redistribution provided the copyright notice and permission notice are included. That is permissive and compatible with most corporate policies, but I am not a lawyer and this is not legal advice; if you vendor workmux into a product, have your own counsel read the LICENSE file. Installing via Homebrew or Cargo means upgrades come from those package managers. The justfile shows the maintainers' own path: `just install` runs `cargo install --offline --path . --locked`, which is for building from a local checkout rather than for end users.

Editorial conclusion

Adopt workmux if you already live in tmux and want each branch to have its own window, its own agent, and a one-command teardown. Do not adopt it if you have no multiplexer configured, or if you want a GUI that hides git from you. Before committing, run workmux init to see the generated .workmux.yaml, and confirm that the default worktree path <project_root>/../<project_name>__worktrees/<name> lands somewhere your editor and ignore rules already tolerate.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. raine/workmux on GitHub
4. README
5. Releases