How to Install workmux on Ubuntu: Git Worktrees and tmux Windows for Parallel Development

workmux calls itself a zero-friction workflow tool for git worktrees and tmux. In practice it gives every task its own sandbox: a git worktree on its own branch, a tmux window laid out the way you like, the ignored files a new checkout needs, and optionally an AI coding agent already working on a prompt. When the task is finished, a single command merges the branch and removes every trace of it. It is written in Rust and aimed squarely at developers running several features or agents at the same time.

workmux is moving quickly and is not carried in the Ubuntu archive. The common install routes are a piped shell script, Homebrew or a manually fetched binary, all of which put you in charge of every future update.

The unofficial deb.griffo.io repository offers a cleaner path: workmux packaged as a proper Ubuntu .deb, shell completions included, and delivered over APT, so you install it and keep it current with the same commands you already use.

Install the Latest workmux on Ubuntu: The Short Version

If you only came for the commands, this adds the repository and installs the latest workmux .deb package on Ubuntu:

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 update
sudo apt install workmux

The rest of this guide explains what each command does, how to verify the install, how to keep workmux up to date, and what to check when something goes wrong.

What Makes workmux Special?

  • 🌿 One command per task - workmux add sets up the worktree and the tmux window together and drops you into it.
  • 🧹 Clean exit - workmux merge merges the work, then deletes the worktree, the window and the local branch for you.
  • 🤖 Agents side by side - Launch Claude Code, Codex, Gemini, OpenCode and friends in separate worktrees, each with its own prompt.
  • 📊 Status at a glance - A TUI dashboard and a tmux sidebar track whether each agent is busy, waiting on you or finished.
  • 📋 Ready-to-run worktrees - Copy .env, symlink dependency folders and run install hooks automatically on creation.
  • 🪟 Pane layouts in YAML - Define the editor, agent, shell and dev server panes you want once and reuse them everywhere.
  • 🔀 PRs and fork branches - Pull a GitHub pull request or someone’s fork branch into a fresh worktree.
  • 🖥️ Flexible backends - tmux out of the box, with kitty, WezTerm and Zellij supported as alternatives.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT rather than a shell installer or Homebrew.
  • Automatic dependency management provided by the Ubuntu packaging, which requires git and recommends tmux.
  • Always tracks upstream releases so you stay near the latest workmux.
  • No compiling from source and no Rust toolchain to look after.
  • Completions for bash, fish and zsh shipped in the same package.
  • Works across supported Ubuntu releases, with the codename detected for you.

Prerequisites

Before starting, confirm you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

git is a hard dependency and tmux a recommended one, so both arrive with a normal install. workmux is only useful inside a running multiplexer; kitty, WezTerm and Zellij work too if you would rather not use tmux. The AI agents it launches are not part of the package, so install the agent CLIs you plan to use (such as Claude Code) on their own.

Step 1: Add the deb.griffo.io Repository

Register the key and repository source:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
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

# Update the package list
sudo apt update

Breaking it down:

  1. Create the keyrings directory - makes sure /etc/apt/keyrings exists with the right permissions.
  2. Install the GPG key - downloads and de-armours the repository key into its own keyring so APT can verify signatures.
  3. Add the repository - writes a signed-by source line, letting lsb_release -sc fill in your Ubuntu codename.
  4. Update the package list - refreshes APT’s view of available packages.

Step 2: Update the Package List

If you did not run the final command above, do it now:

sudo apt update

Step 3: Install workmux

Install with APT:

sudo apt install workmux

APT fetches workmux along with git and, as long as recommended packages are enabled, tmux. On systems configured to skip recommends, install tmux explicitly:

sudo apt install tmux

Step 4: Verify the Installation

The binary is workmux. Check the version:

workmux --version

You should see something like:

workmux 0.1.262

Run workmux --help for the complete command listing, or workmux docs to read the documentation right in the terminal.

Getting Started with workmux

Creating and Finishing a Task

Open tmux, change into a repository, and give your next task a worktree of its own:

# From a tmux pane inside your repository
cd ~/src/my-project

# New branch, new worktree, new tmux window, all at once
workmux add new-feature

# Start the branch from a different base
workmux add hotfix --base production

workmux places the checkout in ../my-project__worktrees/new-feature and names the window wm-new-feature. Wrapping up is just as short:

# Merge the worktree you are currently in and clean everything up
workmux merge

# Prefer a linear history or a single squashed commit?
workmux merge new-feature --rebase
workmux merge new-feature --squash

On a pull-request workflow, push and open the PR as usual; after it lands, workmux remove clears away the worktree and window.

Several Agents at Once

Each worktree can start an agent with a task already in hand:

# Two agents, two worktrees, two tasks
workmux add refactor-user-model -p "Refactor the User model to use composition"
workmux add add-search-endpoint -p "Add a /search endpoint with pagination"

# Pick another agent for a single worktree
workmux add feature/testing -a gemini

# Keep an eye on all of them
workmux dashboard

For agents to show up in the dashboard, run workmux setup once. It finds the agent CLIs you have installed and adds the status hooks, after which each tmux window name also shows whether its agent is working, waiting for input or done.

Moving Between Worktrees

# Show every worktree with its agent, window and merge status
workmux list

# Bring back a worktree's window and pick up the agent's last conversation
workmux open new-feature --continue

# Jump into a worktree directory from a script or shell
cd "$(workmux path new-feature)"

# Drop the worktree and window but hold on to the branch
workmux remove --keep-branch experiment

# Tidy up worktrees whose remote branches are gone
workmux rm --gone

Project and Global Configuration

Out of the box workmux uses sensible defaults. The first thing most projects need is a way to fill in what a clean checkout lacks, so create a project config:

workmux init

This generates .workmux.yaml in the repository. For a Node project it might end up looking like this:

post_create:
  - pnpm install

files:
  copy:
    - .env
  symlink:
    - node_modules

panes:
  - command: <agent>
    focus: true
  - command: pnpm run dev
    split: horizontal

Your own defaults for every repository go in ~/.config/workmux/config.yaml (open it with workmux config edit), and anything set in a project’s .workmux.yaml takes precedence.

Completions and an Alias

Completions for bash, fish and zsh come with the package, so commands and branch names tab-complete in any new shell with nothing to configure. Add an alias if you want to type less:

alias wm='workmux'

Keeping workmux Updated

workmux rides along with your normal Ubuntu upgrades:

sudo apt update && sudo apt upgrade

When a newer workmux appears in deb.griffo.io, apt upgrade installs it alongside your other packages. Given how often workmux ships new releases, having APT pick them up for you is the low-effort way to stay current. Since the package is managed by APT, prefer apt over the built-in workmux update command.

Other Tools from deb.griffo.io

The repository includes many tools that sit well next to workmux:

  • herdr - a terminal workspace manager for orchestrating multiple AI coding agents.
  • Zellij - a terminal multiplexer that workmux can use as its backend.
  • lazygit - a simple terminal UI for inspecting agent changes before you merge.
  • Neovim - the hyperextensible Vim-based text editor, ideal for a workmux pane.

Troubleshooting

GPG or Key Errors

If APT flags the repository as unsigned or the key as invalid, re-import it:

curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot locate workmux:

  1. Re-run sudo apt update after adding the repository.
  2. Verify your Ubuntu release is supported (Jammy, Noble, or newer).
  3. Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

Running workmux Outside a Multiplexer

workmux works out which backend to drive from $TMUX, $WEZTERM_PANE, $KITTY_WINDOW_ID or $ZELLIJ. Run from a plain terminal, it has nothing to attach to. Launch tmux and run your commands from inside it, or set WORKMUX_BACKEND to choose a backend explicitly.

The Dashboard Is Empty

Agents only appear once they can report their state. Install the status hooks with:

workmux setup

Worktrees Start Without .env or Dependencies

Worktrees are fresh checkouts and never include gitignored files. Add what you need under files.copy or files.symlink in .workmux.yaml, and push those changes to worktrees you already have with:

workmux sync-files

An Older workmux Shadows the Package

If you installed workmux earlier through the install script, Homebrew or Cargo, that binary can take precedence over the packaged one:

which -a workmux

Delete the stray copy or reorder your PATH so /usr/bin/workmux wins. When workmux comes from APT, manage upgrades with apt rather than workmux update.

Uninstalling

Remove workmux with:

sudo apt remove workmux

To also remove the repository and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Removing the package leaves your worktrees in place, since they are plain git worktrees; delete any you no longer want with git worktree remove.

Conclusion

On Ubuntu, deb.griffo.io turns workmux into a first-class APT package: no installer script, no manual updates, just a fast way to give every task and every AI agent an isolated worktree and tmux window. workmux add starts the work, workmux merge finishes it, and your existing terminal setup does the rest.

If you routinely juggle parallel features, want several agents working without tripping over each other, or are simply tired of git stash, workmux is an excellent fit, and installing it this way keeps it effortless to keep current.

Frequently Asked Questions

How do I install the latest workmux on Ubuntu?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install workmux. The repository tracks upstream workmux releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for workmux?

Yes. deb.griffo.io publishes workmux as a signed .deb for Ubuntu. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update workmux to the latest version?

Run sudo apt update && sudo apt upgrade. With workmux installed from APT, new releases simply show up as part of your regular system updates.

Does workmux work without tmux?

It needs a terminal multiplexer, but not necessarily tmux. tmux is the default and the package recommends it; kitty, WezTerm and Zellij are supported alternatives.

How do I install workmux on Debian?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Debian specifics: How to install workmux on Debian.

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS and newer, on amd64 and arm64. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream workmux project.