tmux - Background Claude Session Manager

Manage background Claude Code sessions using tmux. Start sessions, send prompts, read responses, and open sessions in Terminal windows.

Commands

Start a new background Claude session

# Basic - starts in current directory
tmux new-session -d -s SESSION_NAME "cd /path/to/dir && claude --dangerously-skip-permissions"

# With initial prompt
tmux new-session -d -s SESSION_NAME "cd /path/to/dir && claude --dangerously-skip-permissions 'YOUR PROMPT HERE'"

Send a prompt to an existing session

tmux send-keys -t SESSION_NAME "your prompt here" Enter

Note: Sometimes an extra Enter is needed:

tmux send-keys -t SESSION_NAME Enter

Read response from a session

tmux capture-pane -t SESSION_NAME -p

For full scrollback:

tmux capture-pane -t SESSION_NAME -p -S -100

List all sessions

tmux ls

Open a session in a Terminal window (hand off to user)

osascript <<'APPLESCRIPT'
tell application "Terminal"
  activate
  do script "tmux attach -t SESSION_NAME"
end tell
APPLESCRIPT

Kill a session

tmux kill-session -t SESSION_NAME

Workflow Example

Start session:

tmux new-session -d -s my-agent "cd /path/to/your/project && claude --dangerously-skip-permissions"
sleep 5

Send prompt:

tmux send-keys -t my-agent "Fix the bug in auth.swift" Enter

Wait and read response:

sleep 15
tmux capture-pane -t my-agent -p

Hand off to user:

osascript -e 'tell application "Terminal" to do script "tmux attach -t my-agent"'

User Instructions

When the user asks to:

"start a background agent" -> create tmux session with Claude
"send prompt to agent X" -> use tmux send-keys
"check agent X" -> use tmux capture-pane
"open agent X" -> open Terminal attached to tmux session
"list agents" -> use tmux ls
"stop agent X" -> use tmux kill-session

Tips

Always wait 5-8 seconds after starting a session for Claude to initialize
After sending a prompt, wait 10-15 seconds for response
Send an extra Enter if the prompt doesn't seem to submit
Use descriptive session names like auth-fix, ui-refactor, etc.