# How to Attach to a Background Session in OpenClaude

> Easily attach to a background OpenClaude session using tmux attach-session or the openclaude attach CLI. Reconnect to your interactive work seamlessly.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/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:

```typescript
// 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:

```bash
tmux list-sessions

```

Look for a session named `openclaude` in the output.

### Attaching Directly

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

```bash
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:

```bash
openclaude attach

```

Internally, this calls the `attachSession()` method defined in [`src/utils/terminalPanel.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/terminalPanel.ts) at line 144. The source constructs the tmux attach command with specific socket configuration:

```typescript
// 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:

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/worktree.ts)** – Constructs the tmux launch and attach commands. At line 1634, the attach command array is assembled as:
  ```typescript
  ['...tmuxGlobalArgs, 'attach-session', '-t', tmuxSessionName]
  ```

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

- **[`src/utils/terminalPanel.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/worktree.ts) (command construction) and [`src/utils/terminalPanel.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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.