Tmux and Claude Code: Sessions, Send-Keys, and the Ceiling

TL;DR Highlight

Running Claude Code agents in tmux works well, but limits appear around four agents.

Who Should Read

A developer running several Claude Code agents at once who spends too much time managing tmux sessions.

Core Mechanics

claude --worktree --tmux does it in one line
- Recent Claude Code creates the git worktree and tmux session together.
- --tmux errors out without --worktree.
- On iTerm2 it uses native panes instead of tmux, so pass --tmux=classic if you want to script against the session.
One session per repo, not per task
- The guide recommends one tmux session per repo, named after the repo.
- Tasks become windows inside that session.
- new-session -A attaches if it exists and creates it if not.
send-keys confuses text with key names
- Bare words like Enter, C-c, Escape, and Space are sent as keypresses.
- Send the prompt with -l and send Enter in a separate call.
- Agent input boxes can swallow an Enter that arrives in the same frame, so sleep 0.3 between them.
capture-pane reads, pipe-pane logs
- capture-pane -p -J joins wrapped lines so grep does not break at the seams.

Community Reactions

Opinion: tmux is still worth it
- One commenter said tmux or screen pays back hugely for just 10 minutes of learning.
- Another told Claude it was in tmux with iTerm, had it spawn subagents into tabs, and asked the primary agent for fleet status, which worked well.
Tools people use instead
- Several commenters switched to herdr and said it shows what's open much better than juggling tmux sessions.
- One uses shpool because they only need persistence, not multiplexing.
- Many others built their own multiplexers (seance, zmx, workmux, agent-deck, and more).
Experience with setup and maintenance cost
- One commenter used Claude Code in tmux from January to August, then moved to the ChatGPT desktop app because of too much tinkering and maintenance.
- Another said too many sessions cause context-switching fatigue and aims for 2 active sessions.
Reaction to the article
- One commenter called it essentially an ad for crystl.
- Another said agents now have --resume, which weakens the main reason for using tmux to avoid losing sessions.

How to Apply

Make a per-repo session with an agent() shell function
- Today, add a function to ~/.zshrc wrapping tmux new-session -A -s NAME -c DIR.
- Derive the name from basename with . replaced by -.
- Run tmux ls and check that sessions are listed per repo.
Change send-keys calls to the -l, sleep, Enter pattern
- Find where your scripts feed prompts to an agent and send only the body with send-keys -l.
- Send Enter in a separate call after sleep 0.3.
- Escape semicolons in the prompt as \;.
Build a status script with capture-pane -J
- Read the last 8 lines of each pane with capture-pane -p -J for your status line.
- Edit the match strings for approval-waiting and working to fit your agent version.
- Recheck them after each agent upgrade since the strings may change.
Decide on a tool switch once you pass 4 agents
- If you keep missing approval prompts, compare agent-specific tools layered on tmux.

Try It

copy & run

# Paste into a tmux terminal (run with Claude Code available in the shell)

# 1) Create a session and window, then start the agent
tmux new-session -d -s api -c ~/code/api
tmux new-window -t api -n auth -c ~/code/api
tmux send-keys -t api:auth "claude" Enter

# 2) Send a prompt (body with -l, Enter separately)
PROMPT="run the test suite and fix what fails"
tmux send-keys -t api:auth -l "$PROMPT"
sleep 0.3
tmux send-keys -t api:auth Enter

# 3) Read the screen: last 30 lines, wrapped lines joined
tmux capture-pane -p -J -S -30 -t api:auth

# Next to try: save a log with pipe-pane
mkdir -p ~/agent-logs
tmux pipe-pane -o -t api:auth 'cat >> ~/agent-logs/api-auth.log'

Terminology

tmuxA terminal manager that runs inside your terminal. Processes stay alive on a server after you close the window, so you can reattach later.

send-keysA command that types text into another pane as if from the keyboard. It lets a script type into an agent's input box.

capture-paneA command that dumps a pane's visible screen or scrollback as text. It's like taking a text screenshot.

git worktreeA git feature that checks out the same repo into multiple folders. Each agent can work on its own branch without file collisions.

ptyA fake terminal that makes a program believe a terminal is attached. The tmux server holds it, so agents keep running after you close the window.