Worktree Lifecycle Management With Tmux and Supervisor

Pairing tmux windows with Supervisor keeps each worktree's setup, processes, and cleanup in sync.

Cover illustration for “Worktree Lifecycle Management With Tmux and Supervisor”
Written by
Ren Matsuyama
Updated
November 21, 2026
Reading time
8 min read
Sources cited
8 sources ↓

Managing git worktrees with tmux and Supervisor is a lifecycle problem. Each worktree needs a provisioned environment, reliable long-lived processes, and coordinated cleanup. The effective design treats those responsibilities as one workflow, with tmux providing the terminal surface, Supervisor managing process liveness, and lifecycle hooks keeping directories, windows, and services in step.

Why git worktrees became infrastructure for parallel development

Two agents cannot safely share a working directory without file collisions and context contamination, while moving that directory to another branch interrupts the environment already in use. Context switches now take work to coordinate who uses the directory and when. A developer reviewing another branch can leave an agent waiting, even when the tasks themselves are independent.

Git worktrees remove that bottleneck by giving each branch its own physical directory while sharing one Git object store for history, refs, and commits. Builds, dependency installation, and tests can run in one worktree while a developer writes code in another. The useful boundary is one window per task. Each task retains its terminal state, editor session, dev server, and agent, so switching context becomes switching windows. However, that independence also creates more environments to provision, monitor, and eventually remove.

Why worktree management is a lifecycle problem, not just a creation problem

Provisioning, supervision, and cleanup must share one lifecycle boundary. When each is done by hand as a separate step, the directory, terminal window, and running processes can fall out of step with the task. A window may survive its worktree, or a worktree may remain after its window closes. Neither condition reliably describes the state of the work. Coordination is therefore an essential part of the environment.

Creation-only automation makes this mismatch especially easy to accumulate. A new checkout still lacks gitignored configuration and uncommitted dependencies, leaving the developer to reconstruct a usable environment before work begins. At the other end, an incomplete cleanup leaves stale directories, local branches, windows, and processes. Creation has become cheap, but removal has not. Each task that runs in parallel adds more state for someone to keep in sync unless both ends of the workflow are automated.

What the creation phase must actually set up

Git creates a directory and checks out a branch. It does not supply the rest of the working environment, including .env, local secrets, node_modules, or a terminal in the correct directory. Provisioning is complete only when those needs are addressed. The creation command therefore has to set up the files, install or link dependencies, and open the paired terminal window so the developer gets a checkout that is ready for work.

For gitignored files, copying and symlinking produce different environments. A symlink shares one file across worktrees, so a change becomes visible everywhere that uses it. A copy gives each worktree an independent snapshot. That distinction is important when environment variables differ by branch, because shared configuration would defeat the intended separation. tmux-worktree provides per-file symlink, copy, or skip selection and stores reusable repository configuration in $XDG_CONFIG_HOME/tmux-worktree/.

workmux uses post-creation hooks for install commands, configuration copies, and dependency symlinks. Those hooks run with the worktree directory as their working directory, tying setup directly to the new environment. Runtime resources need the same deliberate treatment. Two dev servers both launching on port 3000 produce one failure, so port allocation belongs in provisioning. Worktree-indexed port offsets address that collision before the paired terminal opens for work.

How tmux provides runtime isolation without being a process supervisor

Tmux provides persistent sessions and a visible workspace for each worktree. Named sessions survive terminal disconnection, while named windows preserve the one-to-one relationship between a task and its terminal environment. Commands such as send-keys and display-popup provide programmatic control. This makes tmux useful both for direct interaction and as the terminal surface of lifecycle tooling.

Session persistence is not the same as process health. tmux has-session -t name returns an exit code that a watchdog can use to detect and recreate a missing session. However, an existing session does not establish that its dev server or agent is still running. Tmux cannot restart processes automatically, detect crash loops, or handle application exit codes in a structured way. A failed process can leave a pane waiting for someone to notice.

workmux shows agent status in window names and has a dashboard where users can monitor agents, review changes, and send commands across windows. Persistent log routing and reliable child-process shutdown also require process-management machinery. Supervisor does that work alongside the terminal environment.

Where Supervisor fits into the worktree lifecycle

Supervisor manages the processes that need to keep running in a worktree, including dev servers, watchers, and background workers. It supplies restart behavior, structured exit-code handling, log capture and rotation, and configured signal propagation. Tmux remains the place for observation and interaction. The two layers serve the same environment but own different responsibilities.

Each worktree has a supervisord.conf that sets which processes to run, how they restart, and where their logs go. Created during post_create, that configuration becomes part of the provisioned environment. The hook then starts the worktree’s Supervisor instance. On removal, pre_remove stops that instance before the directory disappears, using Supervisor’s process-group model to stop the associated services together.

Container-style deployments also need care with the process tree. Tmux’s double-fork behavior clashes with init systems that expect to own the process tree directly. Supervisor can instead act as PID 1, spawning and monitoring children while forwarding logs to stdout and stderr. In that arrangement, tmux can run as a supervised child or as a separate session outside the supervised group. This changes process ownership while preserving the division between visibility and liveness.

Designing the teardown phase to leave no residue

Creation has an immediate incentive because work cannot begin without it. Teardown has no equivalent pressure once the branch is merged, which makes cleanup easier to postpone or complete only in part. The residue persists after the task is finished. A stale directory, an unused local branch, an orphaned window, and an unstopped dev server are separate remnants of one incomplete lifecycle.

The removal sequence must respect those dependencies. Supervised processes stop before their worktree directory is deleted, and the branch is merged or checked to make sure it is merged before it is removed. Deleting files first can leave Supervisor with file handles still open. The pre_remove hook provides a shutdown checkpoint before worktree removal and aborts on failure, preventing cleanup from proceeding past a failed prerequisite.

workmux coordinates merge and cleanup through workmux merge, which merges the branch, deletes the worktree, closes its tmux window, and removes the local branch. Its guide contrasts this with six distinct manual commands, and its /merge skill delegates the sequence to an agent. Safety checks belong at the destructive boundary. tmux-worktree marks dirty worktrees, requires explicit confirmation for force removal, prompts when branch deletion encounters an unmerged branch, and protects the main worktree and default branch. Without a similarly coordinated removal path, cheap creation predictably becomes stale-worktree accumulation.

Tools that implement the full lifecycle today

workmux is a Rust tool that couples worktree creation and terminal setup through add, then couples merge and cleanup through merge. Its provisioning features include post-creation hooks, configuration copying and symlinking, and automated pane layouts. Agent coordination extends beyond opening a shell. A dashboard supports monitoring and review, a sidebar exposes cross-window agent status, /worktree supports task delegation, and /merge supports autonomous merge-and-cleanup. These features provide lifecycle orchestration into which Supervisor startup and shutdown can be integrated.

Its terminal support includes tmux, with experimental support for kitty, WezTerm, and Zellij. The tool uses the MIT license and is installable through Homebrew, Cargo, mise, or Nix. Terminal choice is therefore an explicit selection criterion.

tmux-worktree takes the form of a pure Bash plugin with no compiled dependencies. It requires tmux 3.2+, fzf, and Git, and operates through floating display-popup windows inside tmux. Three keybindings cover its main lifecycle operations. prefix + W creates, prefix + w switches, and prefix + X removes worktrees. Its creation flow includes an installed-tool picker and reusable gitignored-file synchronization, while its removal flow supplies dirty-state indicators and protective prompts under an MIT license.

mikker’s gwt and claude-start scripts expose a smaller set of primitives. Given a name, gwt creates or reuses a worktree and opens a matching tmux window, while invocation without arguments uses fzf to select an existing worktree. claude-start launches a Claude agent with a structured prompt and explicit tool allowlist. Supervised teardown remains outside those scripts’ scope. The practical choice is between an in-tmux plugin, broader lifecycle and agent orchestration, or minimal shell components for understanding and building a custom workflow.

The supervision architecture debate: tmux as process container vs. tmux as terminal surface

The tmux-native position treats panes as process containers, session existence as a health signal, and lifecycle tooling as the coordination layer. That model provides a direct, inspectable workspace. The systems-administration position instead assigns supervision to managers such as systemd, supervisord, or s6, because reliable exit handling, restart policies, and log routing are distinct from terminal persistence.

Long-lived background work makes the distinction consequential. A pane can stay open after the worker inside it has failed, so session-level liveness cannot take the place of application-level supervision. The practical resolution is to use complementary layers. Tmux owns the terminal surface, Supervisor owns process liveness, and lifecycle tooling couples their creation and removal to the worktree. Neither layer has to imitate the other.

Adding a Supervisor instance to every temporary checkout may exceed what that task requires. Hooks contain the repeated operational cost. For worktrees with long-lived processes, post_create and pre_remove make startup and shutdown automatic once their configuration is in place.

Putting the lifecycle together as a single coordinated workflow

A complete worktree environment has a known state, namely provisioned, running, or cleanly removed. One creation command checks out the branch, supplies gitignored files, runs installation hooks, starts the worktree’s Supervisor instance where needed, and opens its paired tmux window. The environment is ready before the developer switches to it. During work, Supervisor maintains services while tmux exposes interaction and agent status, keeping the runtime and its visible workspace attached to the same task.

The hooks move the environment between those states: post_create sets it up and starts Supervisor, pre_merge runs tests and aborts on failure, and pre_remove stops Supervisor before the directory is removed. Cleanup then coordinates the branch, directory, and terminal window with checks for uncommitted changes and unmerged work before destructive steps. Per-worktree port offsets and database prefixes keep parallel servers and test suites from colliding in resources that Git itself does not isolate.

The implementation path can remain incremental. Start by adopting coordinated creation and teardown through workmux or tmux-worktree, so directories and windows already follow one lifecycle. Supervisor can then enter the post-creation hook for worktrees that run long-lived processes, paired with shutdown in pre_remove. This preserves a clear division of labor while expanding reliability where it is needed.

Methodology & sources

  1. Workmux — Rust application // Lib.rs

    Described workmux's post-creation hooks, pane layouts, dashboard and terminal support.

  2. GitHub - raine/workmux: git worktrees + tmux windows for zero-friction parallel dev · GitHub

    Supplied details on workmux add/merge commands, the merge cleanup sequence and the /merge skill.

  3. GitHub - denesbeck/tmux-worktree: 🌳 A tmux plugin for managing git worktrees. Create, switch, and remove worktrees from a floating popup — each worktree opens in its own tmux window. · GitHub

    Provided tmux-worktree's keybindings, requirements, file sync options and removal safety checks.

  4. GitHub - thomasbrezinski/workmux: git worktrees + tmux windows for zero-friction parallel dev · GitHub

    Mirror of the workmux repository, covering its features, licensing and install options.

  5. Start a new git worktree in tmux · GitHub

    Described the gwt and claude-start scripts as minimal shell primitives.

  6. Git Worktree Isolation Patterns for Parallel AI Agent Development

    Informed the discussion of isolating parallel agents in separate worktrees and the shared resource collisions like ports.

  7. [GIT]: Autonomous Stale Worktree Pruner & Merge Lifecycle Manager · Issue #101 · BowenMichael/agent-manager · GitHub

    Covered the problem of stale worktrees accumulating and the need for automated pruning and merge lifecycle management.

  8. feat: add managed worktree teardown commands by pedronauck · Pull Request #937 · compozy/compozy · GitHub

    Illustrated managed worktree teardown commands as part of a coordinated removal path.

Ren Matsuyama