Keep Claude Code Running After SSH Disconnects (tmux Guide)

Claude Code exits when you close your terminal or close your MacBook lid because of two separate, commonly conflated failure modes — and the fix for one does nothing for the other. Understanding which problem you actually have is the fastest way to stop losing sessions.

TL;DR

Claude Code stops for two distinct reasons: (1) your terminal sends SIGHUP when you close it or disconnect SSH, which tmux intercepts; (2) your laptop sleeps and suspends every process including tmux, which only a cloud VM or lid-sleep prevention (macOS: pmset/Awayke) solves. In 2026, with Dynamic Workflows fanning out to 100+ parallel subagents, one sleep event kills all of them simultaneously — making the cloud VM the architectural fix rather than a workaround.

Why Does Claude Code Stop When You Close Your Terminal?

Claude Code exits on terminal close because the operating system sends SIGHUP (signal 1) to every process in the terminal's session. SIGHUP — short for "signal hangup" — is the OS's way of notifying foreground processes that their controlling terminal has gone away. By default, Claude Code's process doesn't trap this signal, so it exits immediately.

This happens in two specific scenarios:

• You close the terminal window on your local machine — the shell exits and SIGHUP propagates to Claude Code.
• Your SSH connection drops — the remote shell loses its terminal and sends SIGHUP to every process it was running.

These two cases have the same root cause and the same fix: a terminal multiplexer like tmux that creates a persistent process group independent of your terminal window.

Why Does Claude Code Stop When Your MacBook Sleeps?

Claude Code stops when your MacBook sleeps because macOS suspends all processes when the system enters sleep — tmux included. This is a separate failure mode from SIGHUP, and it's the one most guides don't clearly address.

There are two sleep pathways to understand:

• Idle sleep — triggered by inactivity after the display timeout. Can be prevented by caffeinate -i or most "keep awake" apps.
• Lid-close (clamshell) sleep — triggered by closing the MacBook lid. This ignores caffeinate and most IOKit assertions on Apple Silicon. The only reliable software override is pmset disablesleep, which requires admin rights and is what menu-bar tools like Awayke and Decaf use under the hood.

There's also a known Claude Code bug (GitHub issue #21432, open since January 2026): Claude Code spawns caffeinate -i -t 300 child processes repeatedly, even when idle. These loops prevent idle sleep but do nothing for lid-close sleep — and on battery, they prevent the machine from hibernating before the charge runs out, which can cause a hard shutdown that loses your session.

The Two-Failure-Mode Matrix

Fix 1: tmux — Standard Fix for SSH and Terminal Disconnects

tmux (terminal multiplexer) keeps Claude Code running after SSH disconnects by attaching your session to a persistent process group that survives when your terminal goes away.

tmux works by running a background server that owns the session. When you detach or your SSH connection drops, the server keeps running. You reconnect later and reattach — the session is exactly where you left it.

5-Command Setup

# Install tmux (if not already installed)
brew install tmux          # macOS
sudo apt install tmux      # Ubuntu/Debian

# Create a named session for your project
tmux new -s claude

# Run Claude Code inside the session
claude

# Detach without killing Claude Code
# Press: Ctrl+B, then D

# Reconnect from any terminal (including after SSH reconnect)
tmux attach -t claude

Multiple Projects

# Each project gets its own named session
tmux new -s api-rewrite
tmux new -s frontend-cleanup

# List all running sessions
tmux ls

# Attach to a specific one
tmux attach -t api-rewrite

What tmux Does NOT Fix

tmux protects Claude Code from SIGHUP — terminal closes, SSH drops, reconnects. It does not protect against laptop sleep. When your MacBook sleeps, every process on it is suspended, tmux included. The session is still there, but it's frozen until you open the lid.

"No. tmux protects the session from disconnects and closed terminal windows, but when your laptop sleeps, every process on it is suspended, tmux included. tmux only helps on a machine that stays awake: a desktop, home server, or VPS." — Hivra blog

Fix 2: macOS Lid-Close Prevention — Awayke, Decaf, and pmset

If you want Claude Code to keep running when you close your MacBook lid, you need to prevent clamshell sleep — and caffeinate will not do this on Apple Silicon.

caffeinate -i prevents idle sleep only. macOS has a separate sleep pathway for clamshell events that most "keep awake" apps target incorrectly. The only reliable software path is pmset disablesleep, which is what every effective tool in this space uses.

pmset Directly (Requires Admin)

# Prevent all sleep including lid-close
sudo pmset -a disablesleep 1

# Re-enable when done
sudo pmset -a disablesleep 0

Menu-Bar Apps (No Terminal Required)

A small ecosystem of macOS menu-bar apps emerged in 2026 specifically for keeping AI coding agents running:

• Awayke — one-click, free, open source. Uses pmset disablesleep.
• Decaf — agent-aware: auto-sleeps when your agent finishes, so you don't forget to re-enable sleep. Uses pmset.
• LidRun — paid, adds battery floor and thermal safety guards so you don't drain to 0%.
• Sleepless (72 GitHub stars) — battery floor threshold + auto-off timer. Good for overnight runs.

"macOS has a separate sleep pathway for lid-close events, which is independent from the display sleep that most 'keep awake' apps target. The only reliable override is Apple's own pmset disablesleep." — Awayke README

Battery Warning

If you're running Claude Code unattended on battery, lid-sleep prevention is dangerous: the machine can't hibernate before the charge runs out, which causes a hard shutdown that loses your session with no recovery. This is the failure mode behind GitHub issue #21432.

Use lid-sleep prevention on AC power only, or use LidRun/Sleepless which include battery floor protection.

Fix 3: What NOT to Use — nohup

nohup does not work for Claude Code and will create an unrecoverable zombie session.

nohup redirects a process's stdin and stdout to files so it can survive a SIGHUP. That approach works for headless scripts. Claude Code is an interactive TUI — it requires a real terminal for rendering and key capture. When you run nohup claude, Claude Code detaches from its terminal, its UI collapses, and you have a process you can't reattach to.

"nohup will keep the process alive but disconnect its stdin/stdout, leaving you with a zombie you can't reattach to." — cdmckay.org

The one case where nohup works: claude -p "prompt" (headless/non-interactive mode). For interactive sessions, use tmux or screen.

Fix 4: Cloud VM — The Architectural Solution

Moving Claude Code to an always-on cloud VM eliminates both failure modes simultaneously — SIGHUP from SSH drops and laptop sleep — because the VM never turns off.

"The fix is not a flag or a setting. The process has to live on a machine that never sleeps." — Hivra blog

This matters more in 2026 than it did before. Claude Code's Dynamic Workflows can now fan out to 100+ parallel subagents from a single session. A single sleep event kills all of them at once — not just one agent, but your entire orchestration.

Options by Approach

DIY VPS (~$5–10/month): Provision a Hetzner, DigitalOcean, or AWS EC2 instance, install Claude Code, and run it in tmux. You own the setup. You handle provisioning, auth, and security.

Managed cloud workspaces: Daytona provides 90ms cloud workspaces with pre-built environments. Hivra ($9.99/mo) is built specifically for running Claude Code 24/7. Laurel runs on Google Cloud. AgentsRoom focuses on overnight scheduling and background agents.

Docker Cloud Sandboxes (launched September 2026): $0.07/hr for isolated containers. Good for short agent tasks. Sessions don't persist beyond the container lifetime without additional tooling.

For setup guides, see: How to Authenticate Claude Code on a Headless VPS and Hetzner vs DigitalOcean for AI Coding Agents.

The Grass + Daytona Setup: Always-On with Phone Oversight

For developers running long Claude Code sessions who want to close their laptop and monitor from their phone, the Grass + Daytona combination removes the problem at the infrastructure layer while adding mobile-native oversight.

Grass is a machine built for AI coding agents — an always-on cloud VM with Claude Code, Codex, and Open Code pre-loaded, accessible from your laptop, phone, or any automation. The cloud VM product at codeongrass.com is powered by Daytona workspaces: your agent runs on their infrastructure, not your laptop. Closing your MacBook lid has no effect on the session.

The practical workflow:

1. Sign up at codeongrass.com. A Daytona-backed cloud VM is provisioned for you — Claude Code, Codex, and Open Code pre-loaded, ready in seconds. Free tier: 10 hours, no credit card.

2. Start a Claude Code session from the Grass dashboard or mobile app. The agent runs on the cloud VM, not your machine.

3. Close your laptop and walk away. The agent keeps running. No pmset, no tmux babysitting, no caffeinate.

4. Check in from your phone. The Grass mobile app streams your agent's real-time output. When it hits a permission gate — a bash command, a file write — the request forwards to your phone as a native modal. One tap to approve or deny.

5. Come back to finished work. Your session is exactly where you left it. No resume, no lost context.

This pattern — dispatch a task, close your laptop, check from your phone, review the diff — moves you from reactive babysitting to asynchronous delivery. The infrastructure question (will it stay alive?) stops being a workflow decision.

One important note: Daytona workspaces have auto-stop timers enabled by default. For long overnight runs, disable the auto-stop in your workspace settings or use the Grass dashboard to keep it alive.

For the complete Daytona + Grass setup walkthrough, see: How to Set Up Claude Code on Daytona.

Which Fix Should You Use?

FAQ

Why does Claude Code stop when I close my terminal?

Claude Code exits when you close your terminal because the OS sends SIGHUP (hangup signal) to all processes in that terminal session. Claude Code doesn't trap this signal by default, so it exits immediately. The fix is to run Claude Code inside tmux, which creates a process group that survives terminal closes and SSH disconnects.

Does tmux prevent Claude Code from stopping when my MacBook sleeps?

No. tmux keeps Claude Code alive when your terminal closes or your SSH connection drops, but it cannot prevent macOS from suspending all processes when your laptop sleeps. When your MacBook closes its lid or idle-sleeps, every process — including tmux — is suspended. The fix for laptop sleep is either pmset disablesleep (with a tool like Awayke or Decaf) or moving the session to a cloud VM.

Does caffeinate prevent Claude Code from stopping when I close my MacBook lid?

No. caffeinate -i prevents idle sleep only — it doesn't prevent lid-close (clamshell) sleep on Apple Silicon. macOS has a separate sleep pathway for clamshell events that ignores caffeinate and most IOKit assertions. The only software-only fix for lid-close sleep is pmset disablesleep. There is also a Claude Code bug (issue #21432) where Claude spawns caffeinate child processes repeatedly — these hold PreventUserIdleSystemSleep but provide no protection against lid-close sleep.

Should I use nohup to keep Claude Code running?

No. nohup detaches a process's stdin/stdout and works for headless scripts, but Claude Code is an interactive TUI that requires a real terminal for rendering and key capture. Running nohup claude creates a process you can't reattach to. Use tmux instead. The one exception: claude -p "your prompt" (headless/prompt mode) works with nohup because it has no interactive UI.

How do I keep Claude Code running overnight without staying at my laptop?

Three approaches, ordered by complexity: (1) Mac users on AC power can use Awayke or Decaf to prevent lid-close sleep and leave Claude Code running in tmux. (2) Rent a $5/month VPS, install Claude Code, and run it in tmux — it stays on regardless of your laptop. (3) Use a managed service like Grass (always-on cloud VM with phone monitoring), Hivra, or AgentsRoom for overnight scheduling. For Dynamic Workflows running 50+ parallel subagents, a cloud VM is the only architecturally sound option — one laptop sleep event kills every subagent simultaneously.

Can I reconnect to a Claude Code session after my SSH drops?

Yes, if you started Claude Code inside a tmux session on the remote machine. When your SSH connection drops, tmux keeps the process running. Reconnect with ssh user@host and then tmux attach -t claude (or whatever you named the session). The Claude Code session will be exactly where it left off.

Next Steps

1. Quick fix (SSH disconnects): brew install tmux, then tmux new -s claude before starting claude. Takes under 2 minutes.
2. Quick fix (Mac lid-close, AC power): Download Awayke — open source, one-click, free.
3. Permanent fix (laptop sleep, overnight runs): Provision a VPS or set up Grass with Daytona. See How to Authenticate Claude Code on a Headless VPS for the VPS path, or Getting Started with Grass in 5 Minutes for the cloud VM path.
4. Dynamic Workflows: If you're running parallel subagents, skip the laptop fixes entirely — a cloud VM is the right infrastructure from the start.

The goal is to stop making "will my session survive?" a decision you have to think about. Once your agent lives on a machine that never sleeps, it just runs.