What is workmux?
workmux turns one branch into one workspace. A single workmux add creates a git worktree, opens a matching tmux window, copies the files a fresh checkout is missing (.env, credentials), symlinks the ones you do not want to reinstall (node_modules), runs your setup commands and lays out the panes you asked for. workmux merge undoes all of it in one step: merge the branch, delete the worktree, close the window, drop the local branch. No stashing, no branch switching, no half-finished checkout blocking the next task.
⚡ Key Features of workmux
🌿 One Window per Branch
workmux add creates the worktree and the tmux window together, so switching task is switching tab, with its own shell, editor and dev server.
🧰 Worktrees That Actually Work
Fresh worktrees start broken. workmux copies config files, symlinks dependencies and runs your post_create commands so the new checkout is usable immediately.
🤖 Parallel Agents
Run several AI coding agents at once, one per worktree, and track their status in the tmux window name, a TUI dashboard or a live sidebar.
🧹 One-Command Cleanup
workmux merge merges the branch and then removes the worktree, the tmux window and the local branch; workmux remove does the cleanup without the merge.
📄 Configured in YAML
A global config.yaml for your defaults and a per-project .workmux.yaml for pane layouts, hooks and file operations, with monorepo-friendly nesting.
🖥️ Not Only tmux
tmux is the default backend, and kitty, WezTerm and Zellij are supported alternatives, so the workflow follows whichever terminal you already use.
apt upgrade keeps you on the latest version.
📦 Installation from deb.griffo.io
Step 1: Add Repository
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt updateinstall -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
apt updatesudo apt install extrepo
sudo extrepo enable griffo
sudo apt update🆓 There is an always-free mirror. deb-free.griffo.io serves packages free forever, no account, no subscription, at most 2 months behind upstream, security fixes immediately. It currently carries cliamp, Ghostty, lazydocker, Oh My Posh and Zed; workmux is not one of them, so the repository above is the only way to get it today, ask and it can be enrolled.
🧩 About the extrepo option. extrepo is Debian's own tool for external repositories: it writes the sources file and installs the signing key for you, checking the key against signed metadata first. This repository is registered with it as griffo, and the always-free mirror as griffo-free, so on Debian (bookworm, trixie, forky and sid) the commands above are the whole setup.
extrepo sets up the sources file and the key only, so a subscription's credentials still go in /etc/apt/auth.conf.d/deb.griffo.io.conf. Ubuntu is not covered, because extrepo publishes metadata for Debian suites only: there, use the sudo or root commands.
Step 2: Install workmux
# Install latest workmux
sudo apt install workmux
# tmux is the default backend and is only Recommended,
# because kitty, WezTerm and Zellij also work
sudo apt install tmux
# Verify installation
workmux --version# Install latest workmux
apt install workmux
# tmux is the default backend and is only Recommended,
# because kitty, WezTerm and Zellij also work
apt install tmux
# Verify installation
workmux --versionStep 3: First worktree
# Optional: write a .workmux.yaml for this project
cd ~/src/my-project
workmux init
# From inside tmux: branch, worktree, window and panes in one command
workmux add new-feature
# When the work is done: merge and clean everything up
workmux merge
# bash, zsh and fish completions ship with the package
workmux --help🎯 Basic Usage Examples
The everyday loop:
# Create a branch, a worktree and a tmux window
workmux add fix-login
# An existing branch is picked up by name
workmux add existing-work
# Branch off something other than the default base
workmux add hotfix --base production
# Check out a pull request into its own worktree
workmux add --pr 123
# See everything in flight
workmux list
# Merge and tear it all down
workmux merge
# Or throw the work away without merging
workmux remove fix-loginWindows, panes and recovery:
# Create the window without switching to it
workmux add docs-pass --background
# Close a window but keep the worktree and branch
workmux close docs-pass
# Open it again later
workmux open docs-pass
# Rebuild every window after a tmux or machine crash
workmux resurrect
# cd into a worktree from anywhere
cd "$(workmux path fix-login)"Running agents in parallel:
# Install the status hooks and skills for your agent
workmux setup
# Start a worktree with a prompt for the agent
workmux add add-tests --prompt "Add unit tests for the parser"
# Watch every agent in one TUI
workmux dashboard
# Or keep a live status sidebar in tmux
workmux sidebar
# Send an instruction to a running agent
workmux send add-tests "Also cover the error paths"
# Block until that agent is done
workmux wait add-tests🔧 Tool Integrations
workmux deliberately builds on the tools you already run:
- git: worktrees are plain
git worktreecheckouts, sogit, your hooks and your CI see nothing unusual - tmux: one window per worktree, named from the branch, with your pane layout applied automatically
- kitty, WezTerm and Zellij: supported alternative backends if tmux is not your multiplexer
- Coding agents: status tracking, prompt injection and skills for Claude Code and the other agents upstream supports
- Your shell: bash, zsh and fish completions ship with this package, and
alias wm='workmux'is the upstream-recommended shorthand
🚀 Why Choose deb.griffo.io?
- Official Debian: does not package workmux,
apt install workmuxfails on a stock system - cargo install workmux: current, but a Rust compile on every machine, outside apt and without the shell completions
- The upstream install script: convenient, but it writes into your system behind the package manager's back and updates itself on its own schedule
- deb.griffo.io: latest version with automatic updates
- ✅ The Only apt Source: workmux is in neither the Debian nor the Ubuntu archives; this repository packages the official upstream build
- ✅ Agent Support Moves Weekly: which agents workmux can track and drive changes release by release, so being current is the difference between the feature working and not existing
- ✅ Automatic Updates: packages updated within hours of upstream releases
- ✅ Complete Package: the upstream binary as
/usr/bin/workmuxplus bash, zsh and fish completions - ✅ Honest Dependencies: the package depends on
gitand recommendstmux, because kitty, WezTerm and Zellij are supported backends too - ✅ Two Architectures: amd64 and arm64, both statically linked, so the same package runs on every suite
- ✅ Multi-Distribution: works on Bookworm, Trixie, Forky and Sid
- ✅ Easy Maintenance: standard apt commands for updates
📦 Package Build Repository
The Debian packages are automatically built and maintained in this GitHub repository:
- 🧩 workmux-debian - Latest release builds
🔗 Related Packages
Also available from deb.griffo.io:
- lazygit - Terminal UI for the git work inside each worktree
- GitUI - Another fast terminal git client, if you prefer its model
- Zellij - A supported alternative to tmux as the multiplexer backend
- Serie - Commit graph for reviewing what a branch actually did
💝 Support This Project
If this repository saves you time and effort, please consider supporting it!