Can I run multiple instances of Claude Code inside tmux simultaneously?

Yes! You can create multiple tmux windows (Prefix + c) or separate detached sessions (e.g., 'tmux new -s frontend-agent' and 'tmux new -s backend-agent') to run parallel Claude Code CLI agents on distinct microservices.

What happens to Claude Code if my SSH connection drops?

Nothing breaks. Because Claude Code runs inside a server-side tmux daemon, the process remains fully active on the host OS. Reconnect via SSH anytime and type 'tmux attach' to resume your session.

How do I log all Claude Code terminal output automatically?

Use tmux pipe-pane logging. Execute 'tmux pipe-pane -o "cat >> ~/claude-$(date +%F).log"' to write every character of Claude Code reasoning and terminal commands to a persistent log file.

Documentation · Claude Code · AI Workflows

Running Claude Code in tmux:
Persistent AI Agent Workflows

A production-grade guide to orchestrating Anthropic's Claude Code CLI and AI coding agents inside persistent tmux sessions across Linux, macOS, and Windows WSL.

TL;DR Overview

Running Claude Code in tmux:

Prevents AI process termination when SSH connections disconnect or terminal windows close
Allows running autonomous Claude Code background sessions via tmux new -s claude-agent "claude"
Enables 3-pane workflows (AI agent, live dev server, and interactive shell/tests side-by-side)
Supports non-interactive batch execution via claude -p "prompt" --dangerously-skip-permissions
Provides scrollback buffer history retention and automated session logging via tmux pipe-pane

Why tmux is Essential for Claude Code

AI coding agents operate autonomously for extended periods. Running them in a raw terminal tab poses high risks.

⚡ Network Drop Protection

An SSH disconnection or Wi-Fi drop terminates active subshells, aborting mid-flight AI code refactoring. Tmux keeps the process alive on the OS kernel.

🧠 Scrollback & Context Retention

Closing your terminal window destroys active scrollback history. Tmux retains full buffer logs so prompt contexts are never lost.

👁 Side-by-Side Agent Visibility

Autonomous agent loops require visibility alongside live dev server logs, background unit test runs, and git status diffs.

The Ideal 3-Pane AI Agent Layout

Split a single tmux window into 3 dedicated panes for complete control over AI reasoning and application logs.

tmux 3-pane AI workspace visual layout

+------------------------------------+------------------------------------+
|                                    |                                    |
|             PANE 1                 |               PANE 2               |
|      Claude Code CLI Agent         |          Dev Server Monitor        |
|        (executing prompt)          |        (npm run dev / cargo)       |
|                                    |                                    |
+------------------------------------+------------------------------------+
|                                                                         |
|                               PANE 3                                    |
|                     Interactive Shell / Git / Tests                     |
|                                                                         |
+-------------------------------------------------------------------------+
                

⌨️ Keybindings to Build Layout

Prefix + % — Split window vertically
Prefix + " — Split pane horizontally
Prefix + Arrow — Switch focus between panes
Prefix + z — Toggle zoom on Claude Code pane

💡 Pro Tip: Detaching & Reattaching

Press Ctrl+b d to detach from the workspace. Re-attach anytime with:

bash

$ tmux attach -t ai-workspace

Automated Workspace Scripts & Tmuxinator

Construct your 3-pane AI environment in a single command using shell scripts or Tmuxinator declarations.

launch-ai.sh (Automated Workspace Script)

#!/usr/bin/env bash

# launch-ai.sh — Automated Claude Code + Tmux Workspace

SESSION_NAME="ai-dev"

# 1. Create a detached session named 'ai-dev'

tmux new-session -d -s "$SESSION_NAME" -n "workspace"

# 2. Pane 1: Launch Claude Code

tmux send-keys -t "$SESSION_NAME:0.0" "claude" C-m

# 3. Split vertically for Pane 2 (Dev Server)

tmux split-window -h -t "$SESSION_NAME:0.0"

tmux send-keys -t "$SESSION_NAME:0.1" "npm run dev" C-m

# 4. Split bottom horizontally for Pane 3 (Git/Terminal)

tmux split-window -v -t "$SESSION_NAME:0.1"

tmux send-keys -t "$SESSION_NAME:0.2" "git status" C-m

# 5. Focus on Pane 1 (Claude Code) and attach

tmux select-pane -t "$SESSION_NAME:0.0"

tmux attach-session -t "$SESSION_NAME"

~/.config/tmuxinator/ai-dev.yml

name: ai-dev

root: ~/projects/app

windows:

- workspace:

layout: main-vertical

panes:

- claude

- npm run dev

- git status

Unattended Non-Interactive Batch AI Execution

Run headless Claude Code refactoring jobs overnight in detached tmux sessions.

🤖 Headless Single Prompt Execution

Use claude -p "prompt" --dangerously-skip-permissions to execute single-prompt tasks without waiting for manual confirmation.

⚡ Multi-Agent Batch Parallelism

Launch multiple detached tmux sessions in parallel to refactor frontend and backend repos simultaneously.

bash (Headless Parallel Batch Runner)

# 1. Launch detached session for backend refactoring

$ tmux new-session -d -s agent-backend "claude -p 'Refactor authentication module to support OAuth2' --dangerously-skip-permissions > ~/logs/backend-refactor.log 2>&1"

# 2. Launch detached session for unit test generation

$ tmux new-session -d -s agent-tests "claude -p 'Generate jest test suites for all utils' --dangerously-skip-permissions > ~/logs/tests.log 2>&1"

# 3. Check status of running background AI agent sessions

$ tmux list-sessions

Logging Output & Native Desktop Notifications

Keep continuous audit logs of AI code changes and trigger OS push notifications when prompts complete.

bash (Session Pipe-Pane Logging)

# Pipe terminal pane output directly into a daily log file for code auditing

$ tmux pipe-pane -o "cat >> ~/claude-session-$(date +%Y%m%d).log"

~/.tmux.conf (Desktop Activity & Push Notification Hooks)

# Monitor background activity & notify when AI agent finishes prompt

set -g monitor-activity on

set -g visual-activity off

set -g bell-action any

# macOS Desktop Banner Hook via osascript when Claude asks for input

set-hook -g alert-activity 'run-shell "osascript -e \"display notification \\\"Claude Code prompt complete!\\\" with title \\\"tmux AI Agent\\\"\""'

# Increase scrollback buffer for extensive code diffs

set -g history-limit 100000

set -g mouse on

Troubleshooting & Best Practices

Common edge cases when running AI agent subshells inside tmux sessions.

1. Prevent Nested Tmux Sessions

When Claude Code runs shell commands internally, add a safety guard in ~/.zshrc to prevent nested tmux sessions.

2. Overnight Background Tasks

Launch non-interactive AI prompts overnight on remote servers inside detached tmux sessions redirected to a log file.

3. Terminal Truecolor Fix

If syntax highlighting looks corrupt inside tmux, set default-terminal "tmux-256color" in ~/.tmux.conf.

~/.zshrc (Nested Session Safety Guard)

# Prevent accidental nested tmux sessions inside AI subshells

if [ -n "$TMUX" ]; then

alias tmux="echo 'Already inside tmux! Use tmux split-window or new-window.'"

Frequently Asked Questions

Technical guidance for running Claude Code CLI inside terminal multiplexers.

Can I run multiple Claude Code agents in parallel?

Yes. You can create multiple tmux windows (Prefix + c) or launch separate detached sessions (e.g. tmux new -s agent-frontend and tmux new -s agent-backend) to execute independent agent tasks across distinct directories.

What happens if SSH drops while Claude Code is writing code?

Nothing breaks. Because Claude Code runs inside a server-side tmux daemon process, the AI agent continues executing code changes on the OS kernel. Reconnect via SSH and type tmux attach to resume your workspace.

How do I audit and log all Claude Code terminal output?

Use tmux pipe-pane logging: tmux pipe-pane -o "cat >> ~/claude-$(date +%Y%m%d).log". Every line of AI reasoning, generated code diff, and shell command will be saved to a persistent text log file.

Explore Related Documentation

Deepen your tmux workflow knowledge with these essential guides.