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

workmux is an opinionated workflow tool that turns git worktrees and tmux windows into isolated development environments. One command creates a worktree, opens a matching tmux window with your pane layout, copies the files a fresh checkout is missing and starts your AI coding agent; another merges the branch and tears the whole thing down again. Written in Rust, it is built for running several features, or several agents, in parallel without stashing, branch switching or conflicts.

workmux is young, releases often and is not part of the official Debian archive. The usual install routes are a curl-to-shell script, Homebrew or a hand-downloaded binary, and each of them leaves you owning the update problem.

The unofficial deb.griffo.io repository removes that friction: it packages workmux as a standard Debian .deb served over APT, with shell completions included, so installation and updates use the tooling you already run for the rest of your system.

Install the Latest workmux on Debian: The Short Version

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

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?

  • 🌿 Worktree plus window in one command - workmux add creates a git worktree and a matching tmux window and switches you straight to it.
  • 🧹 One-command cleanup - workmux merge merges the branch, removes the worktree, closes the window and deletes the local branch.
  • 🤖 Built for parallel agents - Start Claude Code, Codex, Gemini, OpenCode and others in their own worktree, with a prompt passed on the command line.
  • 📊 Dashboard and sidebar - A TUI dashboard and a tmux sidebar show which agents are working, waiting for input or done.
  • 📋 Automatic setup - Copy .env files, symlink node_modules and run install commands every time a worktree is created.
  • 🪟 Configurable pane layouts - Describe your editor, agent, shell and dev server panes once in YAML.
  • 🔀 Pull requests and forks - Check out a GitHub PR or a fork branch straight into a new worktree.
  • 🖥️ Several backends - tmux by default, with kitty, WezTerm and Zellij as alternatives.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT, no curl-to-shell installer or Homebrew on Linux.
  • Automatic dependency management handled by Debian packaging, which pulls in git and recommends tmux.
  • Always tracks upstream releases so you stay close to the latest workmux.
  • No compiling from source and no Rust toolchain to maintain.
  • Shell completions for bash, fish and zsh installed alongside the binary.
  • Works across supported Debian releases, with the codename detected automatically.

Prerequisites

Before you start, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, Forky, or Sid)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

The package depends on git and recommends tmux, so a default apt install brings both in. workmux needs a terminal multiplexer running to do anything useful; if you prefer kitty, WezTerm or Zellij, install that instead. workmux orchestrates AI coding agents but does not bundle them: install whichever agent CLIs you use (for example Claude Code) separately.

Step 1: Add the deb.griffo.io Repository

Add the signing 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

What each command does:

  1. Create the keyrings directory - ensures /etc/apt/keyrings exists with proper permissions.
  2. Install the GPG key - downloads the repository key and de-armours it into a dedicated keyring for verification.
  3. Add the repository - writes a signed-by source line, with lsb_release -sc supplying your Debian codename.
  4. Update the package list - refreshes APT so it knows about the new packages.

Step 2: Update the Package List

If you skipped the last line, run the update now:

sudo apt update

Step 3: Install workmux

Install workmux with APT:

sudo apt install workmux

APT installs workmux system-wide together with git and, unless you have disabled recommended packages, tmux. If you run with --no-install-recommends, add tmux yourself:

sudo apt install tmux

Step 4: Verify the Installation

The binary is simply workmux. Confirm the version:

workmux --version

You should see output similar to:

workmux 0.1.262

workmux --help lists every command, and workmux docs renders the full documentation in your terminal.

Getting Started with workmux

Your First Worktree

Start tmux, move into a git repository and create a worktree for a new branch:

# Inside tmux, from your repository
cd ~/src/my-project

# Create a branch, a worktree and a tmux window, then switch to it
workmux add new-feature

# Branch from something other than the current branch
workmux add hotfix --base production

The worktree lands in ../my-project__worktrees/new-feature and the window is named wm-new-feature. When you are done, merge and clean up in one go:

# From inside the worktree's tmux window
workmux merge

# Or rebase for a linear history, or squash into a single commit
workmux merge new-feature --rebase
workmux merge new-feature --squash

If your team works through pull requests instead, push the branch, open a PR, and once it is merged run workmux remove to clean up.

Running AI Agents in Parallel

Give each agent a worktree of its own and a prompt to start from:

# Spin up two agents on different 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"

# Use a different agent for one worktree
workmux add feature/testing -a gemini

# Watch them all from one place
workmux dashboard

The dashboard relies on agent status tracking. Run workmux setup once to detect your installed agent CLIs and install the status hooks, and tmux window names will show whether each agent is working, waiting or finished.

Listing, Opening and Removing Worktrees

# List worktrees with agent, window and merge status
workmux list

# Reopen a window for an existing worktree and resume the agent's conversation
workmux open new-feature --continue

# Print a worktree's path for scripts
cd "$(workmux path new-feature)"

# Remove a worktree and its window, keeping the branch
workmux remove --keep-branch experiment

# Clean up worktrees whose remote branches were deleted after a PR merge
workmux rm --gone

Configuring Your Workflow

workmux works with sensible defaults, but a fresh checkout usually lacks .env files and installed dependencies. Generate a project config and tell workmux what each worktree needs:

workmux init

That writes .workmux.yaml to the repository. A typical project config looks like:

post_create:
  - pnpm install

files:
  copy:
    - .env
  symlink:
    - node_modules

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

Personal defaults for every project live in ~/.config/workmux/config.yaml, which workmux config edit opens for you. Project settings override the global ones.

Shell Completions

The package already installs completions for bash, fish and zsh, so tab completion for commands and branch names works as soon as you open a new shell. A short alias saves even more typing:

alias wm='workmux'

Keeping workmux Updated

Because workmux arrived via APT, updates come with the rest of the system:

sudo apt update && sudo apt upgrade

Whenever deb.griffo.io ships a newer workmux, apt upgrade installs it automatically. workmux releases frequently, so letting upgrades ride along with your regular system updates is the easiest way to stay current. When workmux comes from APT, let the package manager handle upgrades rather than the built-in workmux update.

Other Tools from deb.griffo.io

The repository packages plenty of tools that fit naturally alongside workmux:

  • herdr - a terminal workspace manager for running several AI coding agents.
  • Zellij - a terminal workspace and multiplexer, and one of workmux’s supported backends.
  • lazygit - a simple terminal UI for reviewing and committing what your agents changed.
  • Neovim - the hyperextensible Vim-based text editor, a natural fit for a workmux pane.

Troubleshooting

GPG or Key Errors

If APT reports an unsigned repository or an invalid key, import it again:

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 see the workmux package:

  1. Re-run sudo apt update after adding the repository.
  2. Confirm your release is supported (Bookworm, Trixie, Forky, or Sid).
  3. Inspect the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

workmux Cannot Find a Multiplexer

workmux detects its backend from the environment ($TMUX, $WEZTERM_PANE, $KITTY_WINDOW_ID or $ZELLIJ), so it has to run inside one of them. Start tmux first, then run your workmux commands from a tmux pane. To force a particular backend, set WORKMUX_BACKEND.

No Agents Appear in the Dashboard

The dashboard only shows agents that report their status. Install the tracking hooks for your agent CLIs:

workmux setup

New Worktrees Are Missing Files

A worktree is a clean checkout, so gitignored files such as .env or node_modules are not there. List them under files.copy or files.symlink in .workmux.yaml, then apply the change to an existing worktree with:

workmux sync-files

Conflicting workmux Installations

If you previously installed workmux with its install script, Homebrew or Cargo, that copy may shadow the packaged one:

which -a workmux

Remove the stray binary so the APT-managed workmux in /usr/bin is the one you run. Since the packaged workmux is updated through APT, the built-in workmux update is unnecessary here.

Uninstalling

Remove workmux with:

sudo apt remove workmux

To also drop 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

Your worktrees are ordinary git worktrees and survive the removal; clean them up with git worktree remove if you no longer need them.

Conclusion

Installing workmux from deb.griffo.io gives Debian users the glue between git worktrees, tmux and AI coding agents without a bespoke installer or manual updates. Creating an isolated environment is workmux add, finishing it is workmux merge, and everything in between runs in the terminal setup you already have.

Whether you run a handful of agents in parallel or simply want to stop stashing changes every time you switch tasks, workmux is a natural fit, and APT keeps it current with the same apt upgrade you run for everything else.

Frequently Asked Questions

How do I install the latest workmux on Debian?

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 Debian. 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. Once workmux is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

Do I need tmux to use workmux?

You need a terminal multiplexer. tmux is the default backend and the package recommends it, but kitty, WezTerm and Zellij are supported alternatives, which is why tmux is not a hard dependency.

How do I install workmux on Ubuntu?

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

Which Debian releases are supported?

Bookworm 12, Trixie 13, Forky and Sid, on both 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.