Tmux + Claude Code: Run Multiple Agent Sessions at Once

Claude Code is a terminal-first coding agent: you launch it, describe a task, and it plans, edits, and runs commands until the work is done. A single session can take minutes — and with only one terminal, that's minutes of waiting per task.

Tmux changes the equation. Run one Claude Code session per tmux pane (or session), and several tasks proceed at once. This guide shows the setup, the session-naming conventions, and how to resume previous work with --resume.

This is one part of the broader tmux for AI coding workflow — start there for the full picture.

Why Claude Code pairs so well with tmux

Claude Code is long-running and resumable — the two properties that make terminal multiplexing valuable:

• Long-running: a task spans minutes of planning, editing, and test runs. You don't need to watch it.
• Resumable: claude --resume reopens a past conversation, so an interrupted or parked session isn't lost.
• Non-interactive: multiple sessions run side by side in separate shells without conflicting — as long as they touch different files.

Setup: one pane per agent

Named sessions are better than unnamed panes

For serious work, give each agent its own named session rather than a bare pane. Sessions have names you can list, attach to, and kill individually:

# Session per task — names are how you'll find them later
tmux new -s api-feature
claude

# Detach: Ctrl-b d

tmux new -s bug-214
claude
# Ctrl-b d

# See everything running
tmux ls

Or: one session, one agent per pane

When the tasks are short, keep them in one session with the four-pane layout:

tmux new -s agents
# Ctrl-b "  then  Ctrl-b %  then  Ctrl-b %   → 2×2 grid

Pane 1: claude — implement the checkout flow. Pane 2: claude — fix the rate-limit bug. Pane 3: npm test -- --watch. Pane 4: git status for review. All four running, zero waiting.

Resume previous work with --resume

The killer feature for parallel work: park an agent mid-task, detach, and come back to the exact same conversation.

# List past conversations
claude --resume

# Resume a specific one
claude --resume 42

Combine with tmux sessions for a simple routine:

tmux new -s refactor-auth
claude
# Task reaches a natural checkpoint — but the conversation is worth keeping
# Ctrl-b d — session keeps running, agent keeps working

# Later (even on another machine, via SSH)
tmux attach -t refactor-auth
# Same pane, same agent, same context

If the agent finished but you need the conversation back later, claude --resume handles that too — no tmux required.

Monitoring multiple agents

With several sessions running, watch them all at a glance:

tmux ls
# api-feature: 1 windows (created ...)
# bug-214: 1 windows (created ...)
# agents: 1 windows (created ...)

Zoom into any session's pane with Ctrl-b z when you need to read output closely, then zoom back. For persistent labels, name windows too: Ctrl-b , → type a name. The status bar shows the active session and window — see our tmux.conf guide to style it.

Keeping parallel agents safe

Rules that keep multiple Claude Code sessions from stepping on each other:

1. Disjoint files or directories per session. Two agents editing the same file will overwrite each other's work.
2. One repo, one agent at a time for git operations. Commits from two sessions race; let one own the git stage.
3. Check in with git status before starting a new session. A dirty tree confuses agents' diffs.
4. Use sessions for long tasks, panes for quick ones. Sessions are easy to kill individually when done.

FAQ

Does Claude Code conflict with tmux?

No — Claude Code runs fine inside tmux panes and sessions. The terminal detection, colors, and interactive UI all work normally. Some users remap the tmux prefix specifically so it never collides with agent keystrokes (see tmux.conf setup).

Can I run Claude Code in the background without a terminal visible?

Yes — that's what detaching does. Ctrl-b d hides the session, but the agent keeps running and writing files. tmux attach -t <name> brings it back.

How many Claude Code sessions is too many?

Practically, three or four on one laptop is comfortable. Past that, CPU, memory, and API rate limits start to matter more than tmux. Use the four-pane layout as your default and add sessions as needed.

What if my SSH connection drops?

The tmux server and the Claude Code process keep running on the remote machine. Reconnect and tmux attach — everything is where you left it. This is the classic reason to run tmux inside SSH sessions.

Next steps

• The full strategy: tmux for AI coding: parallel agents
• Command reference: tmux cheatsheet
• The 2×2 layout: run 4 AI agents in parallel
• Config: tmux.conf for faster AI coding