Claude Persistent Sessions with tmux

Claude Persistent Sessions with tmux

New to tmux?

This page is a focused recipe for keeping Claude Code alive on the server. For a complete tmux tutorial covering sessions, panes, customisation, and automation, see the tmux Tutorial.

Overview

This guide explains how to run Claude Code in persistent tmux sessions on the Hetzner server, allowing you to maintain long-running Claude sessions that survive disconnections and can be accessed from anywhere.

What is tmux?

tmux (terminal multiplexer) is a tool that allows you to:

• Create persistent terminal sessions that continue running even after you disconnect
• Switch between multiple sessions easily
• Detach from a session and reattach later
• Keep processes running in the background

Benefits for Claude Code

Running Claude Code in tmux provides several advantages:

• Persistence: Your Claude session continues running even if your SSH connection drops
• Accessibility: Reconnect to your Claude session from any device
• Multi-tasking: Run Claude in one session while working in another terminal
• Reliability: Never lose your conversation history or context due to network issues
• Convenience: Quick commands to attach/detach without interrupting Claude’s work

Available Commands

Your .bashrc has been configured with convenient aliases for tmux management:

Command	Description	Example
tclaude	Quickly attach to the Claude session	tclaude
tls	List all tmux sessions	tls
ta <name>	Attach to a specific session	ta work
tn <name>	Create a new named session	tn myproject
tk <name>	Kill a specific session	tk old-session
twork	Create a separate work session (won’t auto-attach to Claude)	twork
freetm	Start bash shell without auto-tmux	freetm

Quick Start Guide

Step 1: Create Your Persistent Claude Session

# SSH into the Hetzner server
ssh root@your-server.com

# Create a new tmux session named "claude"
tmux new-session -s claude

# Start Claude Code
claude

You now have Claude running in a persistent session!

Step 2: Detach from the Session

To leave Claude running in the background while you do other work:

Press: Ctrl+b, then press d

This detaches you from the tmux session. Claude continues running in the background.

Step 3: Reattach to Your Claude Session

To return to your Claude session from anywhere:

tclaude

That’s it! You’re back in your Claude session exactly where you left off.

Common Workflows

Scenario 1: Working with Claude While Monitoring Logs

# Terminal 1: Attach to Claude
tclaude

# Detach with Ctrl+b, d

# Terminal 2: Create a work session for logs
twork
tail -f /var/log/nginx/access.log

# Switch back to Claude anytime with tclaude

Scenario 2: Multiple Projects

# Create session for project A
tn project-a
claude

# Detach: Ctrl+b, d

# Create session for project B
tn project-b
claude

# List all sessions
tls

# Switch between projects
ta project-a
ta project-b

Scenario 3: Recovering After Network Disconnection

# If your SSH connection drops, simply:
ssh root@your-server.com
tclaude

# You're back in your Claude session!

Essential tmux Commands

Session Management

Keyboard Shortcut	Action
Ctrl+b, d	Detach from current session
Ctrl+b, $	Rename current session
Ctrl+b, s	List all sessions (interactive)

Window Management (Multiple Windows in One Session)

Keyboard Shortcut	Action
Ctrl+b, c	Create new window
Ctrl+b, n	Next window
Ctrl+b, p	Previous window
Ctrl+b, 0-9	Switch to window number
Ctrl+b, ,	Rename current window
Ctrl+b, &	Kill current window

Pane Management (Split Screen)

Keyboard Shortcut	Action
Ctrl+b, %	Split pane vertically
Ctrl+b, "	Split pane horizontally
Ctrl+b, Arrow Keys	Navigate between panes
Ctrl+b, x	Kill current pane

Best Practices

1. Use Descriptive Session Names

# Good
tn claude-thrivesend
tn claude-mgslg
tn monitoring

# Avoid
tn session1
tn temp

2. Regularly Clean Up Old Sessions

# List all sessions
tls

# Kill sessions you no longer need
tk old-session-name

3. Use Multiple Windows Instead of Multiple Sessions

For related work, use windows within the same session:

# Attach to claude session
tclaude

# Create new window: Ctrl+b, c
# Now you have Claude in window 0, and can work in window 1

4. Rename Your Session for Clarity

If you created session “0” and want to use it for Claude:

# Attach to the session
ta 0

# Rename it: Ctrl+b, $
# Type: claude
# Press Enter

# Now you can use tclaude to attach to it

Troubleshooting

Issue: “no sessions” when running tclaude

Solution: You haven’t created a “claude” session yet.

# Create the claude session
tmux new-session -s claude
claude

Issue: “session not found: claude”

Solution: The session may have been killed or renamed.

# List all sessions to find it
tls

# If you see a session with a different name, attach to it
ta <session-name>

# Rename it to "claude": Ctrl+b, $

Issue: Accidentally killed the Claude session

Solution: Just create a new one!

tn claude
claude

Your conversation history with Claude is stored in Claude’s cloud, so you won’t lose your context.

Issue: Can’t detach from tmux

Solution: Make sure you’re pressing the key combination correctly:

1. Press and hold Ctrl
2. Press b (while holding Ctrl)
3. Release both keys
4. Press d

Advanced Usage

Sharing Sessions with Team Members

Multiple users can attach to the same tmux session simultaneously:

# User 1 creates session
tmux new-session -s shared-claude
claude

# User 2 (on another SSH connection) can attach to the same session
tmux attach-session -t shared-claude

# Both users see the same Claude session in real-time!

Auto-start Claude on Server Boot (Optional)

To automatically start Claude in tmux when the server boots:

# Add to crontab
crontab -e

# Add this line:
@reboot tmux new-session -d -s claude 'cd ~ && claude'

Custom tmux Configuration

Create a ~/.tmux.conf file to customize tmux behavior:

# Example: Change prefix from Ctrl+b to Ctrl+a
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

# Enable mouse support
set -g mouse on

# Start window numbering at 1
set -g base-index 1

# Increase scrollback buffer
set-option -g history-limit 10000

After creating the config, reload it:

tmux source-file ~/.tmux.conf

Security Considerations

1. Session Isolation

Each tmux session runs with the permissions of the user who created it. On a shared server, ensure you trust all users who can access your sessions.

2. Automatic Logout

For security, consider configuring automatic session timeout:

# Add to ~/.tmux.conf
set -g lock-after-time 1800  # Lock after 30 minutes of inactivity

3. Sensitive Information

Be cautious about leaving Claude sessions with sensitive information visible. Consider locking your tmux session when stepping away:

# Lock current session: Ctrl+b, Ctrl+x
# Or from command line:
tmux lock-session

Additional Resources

• Official tmux documentation
• tmux Cheat Sheet
• Practical tmux Tutorial

Summary

With tmux and the configured aliases, managing persistent Claude sessions is simple:

1. Create: tn claude → claude
2. Detach: Ctrl+b, d
3. Reattach: tclaude
4. List: tls

Never lose your Claude session again! 🚀

---

Last updated: {{ git_revision_date_localized }}