workmux: git worktrees + tmux for parallel AI agents

Recently, with AI-assisted coding gaining momentum, a long-standing and not that well-known git feature is finding new relevance. The feature is git worktrees, the ability to have multiple branches checked out simultaneously, each in its own directory.

Running multiple agents in parallel is becoming increasingly common, and agents benefit from the isolation worktrees provide. If agents share the same working tree, they quickly run into each other's type errors and broken builds. Separate worktrees also make reviewing their changes easier, because you see the diff for a single unit of work. Even outside of agents, worktrees reduce pain from context-switching. No need to stash/commit, reinstall dependencies, or lose editor state.

I've been curious about worktrees since before LLM agents, but I've always struggled with the low-level tooling the vanilla git worktree CLI provides. And despite having tried worktree wrapper CLIs that make the use of worktrees more ergonomic, I haven't found them to quite fit my tmux-based workflow.

This led to workmux, a utility that ties worktrees with tmux windows and streamlines the flow from starting a new feature in a worktree, to merging it.

This has turned out to be the right level of abstraction for my terminal-centric workflow. While tools like Vibe Kanban and Claude Squad offer alternative UIs, workmux fits naturally into existing tmux workflows. Each worktree maps to a tmux window, where it runs the agent and any other commands you've configured. Workmux also shows agent status in the window list, so you can tell at a glance which agents are working or done.

Here's what it looks like:

#Getting started

Install via Homebrew or Cargo:

brew install raine/workmux/workmux
# or
cargo install workmux

The core workflow is two commands:

# Create a worktree and tmux window
workmux add feature-name

# When done, merge to main and clean up
workmux merge

The add command creates the worktree, opens a tmux window, and switches you to it. merge merges your branch into main and removes everything: worktree, window, and the local branch. This is the most basic workflow, but add supports many useful options, like checking out a pull request with --pr or generating the branch name from a given prompt with --auto-name. Check the command documentation for the complete list.

#Configuration

The tool works out of the box with sensible defaults, but you can customize it with a .workmux.yaml in your project:

panes:
  - command: <agent>
    focus: true
  - command: npm install && npm run dev
    split: horizontal

files:
  symlink:
    - .turbo # share build cache across worktrees
  copy:
    - .env

The <agent> placeholder expands to whatever agent you're using (claude, codex, gemini, etc.). File symlinks let you share caches across worktrees, and copies handle config files that need to be per-worktree.

With this setup, the tmux window list becomes a dashboard. You can dispatch tasks to agents in separate worktrees. A quick glance shows who's thinking, who needs input, and who's ready for review.

After a few weeks of dogfooding, workmux has changed my standard git workflow. Now, instead of plain branches, I tend to go for a dedicated worktree for each task, be it a feature or reviewing someone else's code. The mental model of having a tmux window per task feels very natural. Each one is isolated, with its own terminal state, editor session and a running dev server.

The next post explores more advanced agentic workflows, like how to brainstorm tasks with a main agent and delegate them to worktree agents. In the meantime, feel free to check out workmux.

Read next Using git worktrees to parallelize AI coding a workflow for delegating tasks to parallel worktree agents.