tmux vs git worktrees for running multiple agents
Checked August 15, 2026. The tmux and git behavior described here is stable and unlikely to age. The tooling landscape around it moves fast, so treat anything about specific products as dated to that day.
This is a false choice, and knowing why saves you a rebuild of your setup later. tmux and git worktrees solve different problems. tmux keeps sessions alive and lets you see several at once. Worktrees keep parallel agents from editing the same files. If you run more than one agent like Claude Code or Codex at a time, you usually end up wanting both, and there is a third problem neither one touches.
at a glance
| tmux | git worktrees | |
|---|---|---|
| Problem it solves | sessions die when the terminal closes | two agents editing the same files |
| What you get | persistent sessions, split panes, detach and reattach | one checkout per branch, real filesystem isolation |
| What it does not do | nothing about file conflicts | nothing about keeping sessions alive or visible |
| Cost to learn | prefix keys, config, a session model | a few git commands and a cleanup habit |
| Where it hurts | checking six panes by eye to find the one that needs you | stale worktrees, branch juggling, merge discipline |
what tmux actually solves
A terminal session normally lives and dies with its window. Close the tab, drop the SSH connection, or reboot, and the agent running inside it is gone mid-task. tmux breaks that link: sessions run inside a server process, and your terminal is just a view onto them. You can detach, go home, reattach, and the agent never noticed. Split panes give you several sessions on one screen, which is why almost every "run a team of agents" tutorial starts with a tmux grid.
What tmux does not do is anything about files. Two agents in two tmux panes pointed at the same repository share one working directory. They will overwrite each other's edits, trip over each other's git state, and neither tmux nor the agents will warn you. Our tmux for AI agents guide covers the setup; running an agent team in tmux covers the workflow.
what git worktrees actually solve
A worktree is a second full checkout of your repository, on its own branch, in its own directory, backed by the same .git data. One command:
git worktree add ../myrepo-feature feature-branch
Now an agent working in ../myrepo-feature cannot touch the files an agent in
your main checkout is editing. That is the whole trick, and it is the correct fix for
parallel agents on one repo. Branches alone do not do this; two sessions on different
branches in the same directory still share the same files on disk, which is why
worktree vs branch is its own question.
The costs are bookkeeping. You create worktrees, remember which directory belongs to which task, merge the branches when work lands, and clean up afterward. Skip the cleanup and you eventually meet "cannot delete branch used by worktree". And worktrees do nothing about session lifetime: close the terminal and the agent dies, its conversation with it.
the real answer is both, and then a third problem
Persistence and isolation are orthogonal, so the standard DIY setup for running multiple Claude Code instances is tmux for the sessions plus one worktree per agent. It works, and if you enjoy maintaining your tooling, it is free and infinitely scriptable.
What it leaves unsolved is supervision. Six panes in a tmux grid are six untyped streams of text. Nothing tells you which agent is blocked on an approval, which finished half an hour ago, and which has been sitting on a question since lunch. You find out by reading every pane, on a schedule, yourself. Approval prompts scroll past inline. The more agents you add, the more your job becomes polling a wall of terminals, which is exactly the work you were trying to hand off.
where crystl fits
Disclosures first: crystl is our product, macOS only, closed source, with a free tier and paid orchestration features at $170 a year. tmux and git are free, run everywhere, and will outlive us all. If you are happy maintaining the DIY setup, keep it; this page's advice stands without crystl in it.
What crystl changes is that the combo above becomes the default instead of the setup. Isolated shards create the worktree and branch for you, one per agent. Conversation history survives closed windows and reboots without a multiplexer. And the supervision gap is the actual product: an activity panel showing every session's state at once, and approval panels that find you instead of scrolling past in pane four. If your tmux grid has started to feel like a job, that is the problem it is for.
how to choose
- One agent at a time, sessions keep dying: tmux alone is enough.
- Two or more agents on the same repository: worktrees, whatever else you use.
- Several long-running agents, DIY spirit, any platform: tmux + worktrees.
- On a Mac, several agents daily, tired of polling panes: crystl does the worktrees and the watching for you.