Run multiple Claude Code sessions in tmux

To run several Claude Code sessions in tmux, give each one its own git worktree and its own tmux window or session. Claude Code can do both at once: claude -w feature-auth --tmux creates a worktree on a new branch and a tmux session for it. Detach with Ctrl-b d and the agents keep working; tmux attach brings you back.

This is the do-it-yourself way to run agents in parallel. It costs nothing extra, works over SSH, and is a good fit if you already live in a terminal. Our broader guide to running Claude Code agents in parallel compares it with the other options.

Why a worktree for every session#

Two Claude Code sessions in the same folder edit the same files. One rewrites a function while the other is halfway through reading it, and you get a mess neither of them made on purpose.

A git worktree is a second checkout of the same repository, on its own branch, sharing the same history. Anthropic's worktree docs put it plainly: each session gets "a separate copy of the files to edit, so one session can build a feature while a second fixes a bug". Our post on a worktree per chat explains why we made it the default.

The quick way: --worktree with --tmux#

1. Run Claude once in the repository, so it trusts the folder: claude, then exit.
2. Start the first session: claude -w feature-auth --tmux
3. Start the second from another terminal: claude -w fix-billing --tmux
4. List what's running: tmux ls

Each worktree lands in .claude/worktrees/<name>/ on a branch named worktree-<name>. Add .claude/worktrees/ to .gitignore so they don't show up as untracked files. Anthropic's CLI reference says --tmux uses iTerm2's own panes when it can; --tmux=classic forces plain tmux.

The manual way: one tmux session, one window per agent#

If you want everything in one place:

tmux new -s agents
git worktree add ../app-auth -b feature-auth
cd ../app-auth && claude

Then Ctrl-b c opens a new window for the next agent:

git worktree add ../app-billing -b fix-billing
cd ../app-billing && claude

The tmux keys you'll use, from the tmux wiki:

Name each window after its branch (Ctrl-b ,) so you can tell them apart at a glance. Scrolling back through a conversation inside tmux depends on which renderer Claude Code uses: Claude Code in tmux: scrolling, focus and display fixes.

Set each worktree up first#

A worktree is a fresh checkout: no node_modules, no .env. Install dependencies in each one, or ask Claude to. Claude Code copies gitignored files you list in a .worktreeinclude file at the project root into every worktree it creates, such as .env and .env.local.

Two dev servers on one port is the next collision: give each worktree its own port, for example through a PORT variable in its .env. And watch disk space: each worktree is a full checkout (how to keep that in check).

Cleaning up#

Exit a --worktree session and Claude checks for work first. A clean worktree from a session you never named is removed with its branch; otherwise it asks whether to keep it. The full exit rules are in Claude Code --worktree, explained. For worktrees you made by hand:

git worktree list
git worktree remove ../app-auth

Where tmux runs out#

tmux handles the windows. It doesn't merge branches, tell you which agent is waiting for an answer, or follow you to your phone, and every session spends from the same Claude plan, so three agents empty it about three times as fast. Claude Code's own agent view puts its background sessions in one list, with the ones that need you at the top, but it covers Claude Code only.

That's the gap Shuriken fills. Every chat gets its own worktree and branch the way the commands above set up, an Activity panel shows what each agent is doing, Finish merges the branch when it's done, and the chats are on your phone too. When one of your Claude accounts nears its limit, Shuriken can move the chats to another account you own and keep going.