How to Attach to a Background Session in OpenClaude

Attach to a background OpenClaude session by running tmux attach-session -t openclaude or use the openclaude attach CLI helper, both of which reconnect you to the persistent tmux session that hosts your interactive work.

OpenClaude runs interactive sessions inside tmux sessions, allowing the UI to detach from the foreground process while keeping work running in the background. When you start a new OpenClaude session, the tool creates (or re-uses) a tmux session named openclaude that lives independently of the terminal window that launched it. This architecture enables you to disconnect, close your terminal, and later reconnect to the same running session without losing context.

Understanding OpenClaude's Background Session Architecture

OpenClaude leverages tmux to maintain persistent background sessions. When you initiate a query marked as "background", the system preserves the session state so you can re-attach later.

The Role of queryLifecycle.ts

According to the OpenClaude source code, the queryLifecycle.ts file handles the transition to background mode. At line 88, the case 'background' branch marks a query as background-enabled, allowing the session to persist after detaching:

// src/utils/queryLifecycle.ts#L88
case 'background':
  // Handle background query persistence

This mechanism ensures that when you detach from the UI, the underlying tmux session continues running your tasks.

Method 1: Manual tmux Attachment

The most direct way to reconnect uses standard tmux commands targeting the OpenClaude session name.

Listing Available Sessions

First, verify that your OpenClaude session is still running:

tmux list-sessions

Look for a session named openclaude in the output.

Attaching Directly

Re-attach to the background session using the session name:

tmux attach-session -t openclaude

Your terminal restores to the exact UI state where you left off, with all background tasks still executing. To detach without killing the session, press Ctrl+b followed by d.

Method 2: Using the OpenClaude CLI Helper

OpenClaude provides a wrapper command that internally invokes the same tmux attach logic. If you launched OpenClaude previously and closed the terminal, simply run:

openclaude attach

Internally, this calls the attachSession() method defined in src/utils/terminalPanel.ts at line 144. The source constructs the tmux attach command with specific socket configuration:

// src/utils/terminalPanel.ts#L144
private attachSession(): void {
  // ...
  ['-L', getTerminalPanelSocket(), 'attach-session', '-t', TMUX_SESSION]
  // ...
}

This approach handles socket configuration automatically, making it more reliable than manual tmux commands when OpenClaude uses non-default socket paths.

Method 3: Programmatic Attachment from Scripts

If you need to embed session attachment within automation scripts, replicate the CLI logic using Node.js child process execution:

import { execSync } from 'child_process';

const TMUX_SESSION = 'openclaude';
const socketPath = '/path/to/terminal/panel/socket'; // Retrieved from getTerminalPanelSocket()

try {
  execSync(
    `tmux -L ${socketPath} attach-session -t ${TMUX_SESSION}`,
    { stdio: 'inherit' }
  );
} catch (error) {
  console.error('Failed to attach to OpenClaude session:', error);
}

This directly runs the tmux attach command, bypassing the higher-level CLI while maintaining socket compatibility with the OpenClaude architecture.

Key Source Files and Implementation Details

Three core files implement the attach functionality:

• src/utils/worktree.ts – Constructs the tmux launch and attach commands. At line 1634, the attach command array is assembled as:

  ['...tmuxGlobalArgs, 'attach-session', '-t', tmuxSessionName]

  This file defines the default session name logic used across the application.

• src/utils/terminalPanel.ts – Provides the UI-level attachSession() method that the openclaude attach CLI command invokes. This method handles socket configuration and terminal restoration at line 144.

• src/utils/queryLifecycle.ts – Manages the transition to background mode at line 88, ensuring sessions persist after the user detaches from the foreground process.

Together, these components create a detached session architecture that survives terminal closure and system sleep cycles.

Summary

• OpenClaude uses tmux sessions named openclaude to maintain persistent background work
• Manual attachment: Run tmux attach-session -t openclaude to reconnect directly
• CLI helper: Use openclaude attach for automated socket configuration and session restoration
• Source implementation: Key logic resides in src/utils/worktree.ts (command construction) and src/utils/terminalPanel.ts (UI attachment interface)
• Detach safely using Ctrl+b then d to keep the session running in the background

Frequently Asked Questions

What happens to my OpenClaude session if I close the terminal?

Your session continues running in the background. OpenClaude creates a tmux session that persists independently of your terminal window. When you close the terminal, you merely detach from the tmux session; the underlying processes keep executing. You can reconnect later using either tmux attach-session -t openclaude or the openclaude attach command.

Can I run multiple OpenClaude sessions simultaneously?

The default implementation in src/utils/worktree.ts uses a single session name (openclaude), which means running multiple instances typically re-uses the same session. To run multiple isolated sessions, you would need to modify the tmuxSessionName variable or launch separate tmux sessions with distinct names before starting OpenClaude.

How do I detach from an OpenClaude session without killing it?

Press Ctrl+b followed immediately by d (the tmux prefix key plus detach command). This returns you to your regular shell while keeping the OpenClaude session active in the background. The queryLifecycle.ts logic ensures that background queries continue processing while detached.

Where does OpenClaude store the tmux session name configuration?

The session name is defined in src/utils/worktree.ts, where the tmuxSessionName variable defaults to openclaude. The attach-session command constructed at line 1634 references this variable. You can inspect or modify this value in the source code if you need to customize the session naming convention for your environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}