tmux

Original source / Raw SKILL.md

---
name: tmux
description: "Remote control tmux sessions for interactive CLIs, background tasks, and services. Supports sub-tasks, long-running processes, and service management with session persistence and automatic cleanup."
license: MIT
---

# tmux Skill

Use tmux as a programmable terminal multiplexer for interactive work, background tasks, and service management. Works on Linux and macOS with stock tmux; uses a private socket to avoid interfering with your personal tmux configuration.

## Quickstart (isolated socket)

### CLI Mode

```bash
# Create a new session
bun ~/.pi/agent/skills/tmux/lib.ts create my-task "echo 'Hello World'" task

# List all sessions
bun ~/.pi/agent/skills/tmux/lib.ts list

# Capture output
bun ~/.pi/agent/skills/tmux/lib.ts capture pi-task-my-task-20250107-123456

# Kill a session
bun ~/.pi/agent/skills/tmux/lib.ts kill pi-task-my-task-20250107-123456
```

### TUI Mode

```bash
# Launch interactive TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# Or create test sessions first
bun ~/.pi/agent/skills/tmux/test-tui.ts
bun ~/.pi/agent/skills/tmux/tui.ts
```

See [TUI.md](TUI.md) for detailed TUI documentation.

## Socket Convention

- **Socket Directory**: `${TMPDIR:-/tmp}/pi-tmux-sockets`
- **Default Socket**: `/tmp/pi-tmux-sockets/pi.sock`
- **Environment Variable**: `PI_TMUX_SOCKET_DIR` (optional override)

All Agent sessions use a private socket to avoid conflicts with your personal tmux configuration.

## Session Naming

Sessions are named using the pattern: `pi-{category}-{name}-{timestamp}`

- **Categories**:
  - `task`: Temporary sub-tasks (compilation, testing)
  - `service`: Long-running services (dev servers, databases)
  - `agent`: Agent-specific tasks (training, data processing)

- **Examples**:
  - `pi-task-compile-20250107-123456`
  - `pi-service-dev-server-20250107-123456`
  - `pi-agent-training-20250107-123456`

## CLI Commands

### Create Session
```bash
bun ~/.pi/agent/skills/tmux/lib.ts create <name> <command> [category]
```

Creates a new tmux session and automatically prints the monitoring command.

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts create compile "make clean && make all" task
```

### List Sessions
```bash
bun ~/.pi/agent/skills/tmux/lib.ts list [filter]
```

Lists all sessions with status and last activity time.

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts list
bun ~/.pi/agent/skills/tmux/lib.ts list service
```

### Session Status
```bash
bun ~/.pi/agent/skills/tmux/lib.ts status <id>
```

Shows detailed information about a session.

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts status pi-task-compile-20250107-123456
```

### Send Keys
```bash
bun ~/.pi/agent/skills/tmux/lib.ts send <id> <keys>
```

Sends keystrokes to a session. Uses literal mode to avoid shell escaping.

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts send pi-task-python-20250107-123456 "print('Hello')"
```

### Capture Output
```bash
bun ~/.pi/agent/skills/tmux/lib.ts capture <id> [lines]
```

Captures pane output (default: 200 lines).

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts capture pi-task-compile-20250107-123456 500
```

### Kill Session
```bash
bun ~/.pi/agent/skills/tmux/lib.ts kill <id>
```

Terminates a tmux session.

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts kill pi-task-compile-20250107-123456
```

### Cleanup Old Sessions
```bash
bun ~/.pi/agent/skills/tmux/lib.ts cleanup [hours]
```

Removes inactive sessions older than the specified age (default: 24 hours).

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts cleanup
bun ~/.pi/agent/skills/tmux/lib.ts cleanup 48
```

### Attach to Session
```bash
bun ~/.pi/agent/skills/tmux/lib.ts attach <id>
```

Prints the command to attach to a session interactively.

**Example**:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts attach pi-task-python-20250107-123456
# Output: tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t pi-task-python-20250107-123456
```

### Sync Sessions
```bash
bun ~/.pi/agent/skills/tmux/lib.ts sync
```

Synchronizes session status with tmux actual state.

### TUI Management
```bash
bun ~/.pi/agent/skills/tmux/tui.ts
```

Launches an interactive Terminal User Interface (TUI) for managing tmux sessions.

**Features**:
- Visual session list with color-coded status
- Real-time auto-refresh (every 5 seconds)
- Keyboard navigation and shortcuts
- Create, kill, capture, and monitor sessions

**Keyboard Shortcuts**:
- `↑/↓` - Navigate session list
- `r` - Refresh session list
- `n` - Create new session
- `c` - Capture session output
- `s` - Show session status
- `a` - Show attach command
- `k` - Kill session (requires confirmation)
- `q/Esc` - Exit TUI

**Example**:
```bash
# Launch TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# Or create test sessions first
bun ~/.pi/agent/skills/tmux/test-tui.ts
bun ~/.pi/agent/skills/tmux/tui.ts
```

## Session Persistence

Session information is stored in `${TMPDIR:-/tmp}/pi-tmux-sessions.json`. This allows:
- Cross-session recovery
- State tracking across Agent restarts
- Automatic cleanup of stale sessions

**Storage Format**:
```json
{
  "sessions": {
    "pi-task-compile-20250107-123456": {
      "id": "pi-task-compile-20250107-123456",
      "name": "compile",
      "category": "task",
      "socket": "/tmp/pi-tmux-sockets/pi.sock",
      "target": "pi-task-compile-20250107-123456:0.0",
      "command": "make clean && make all",
      "status": "running",
      "createdAt": "2025-01-07T12:34:56Z",
      "lastActivityAt": "2025-01-07T12:35:00Z"
    }
  },
  "lastSync": "2025-01-07T12:35:00Z"
}
```

## Use Cases

### TUI Session Management
Use the interactive TUI for visual session management:

```bash
# Launch TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# Navigate with arrow keys, use shortcuts to manage sessions
# Press 'n' to create a new session interactively
# Press 'c' to capture output from selected session
# Press 'k' to kill a session (with confirmation)
```

### Sub-task Execution
Execute temporary tasks that require monitoring:

```bash
# Start compilation
bun ~/.pi/agent/skills/tmux/lib.ts create compile "make all" task

# Wait for completion (in script)
bun ~/.pi/agent/skills/tmux/lib.ts capture pi-task-compile-20250107-123456 | grep "Build successful"

# Get result
bun ~/.pi/agent/skills/tmux/lib.ts capture pi-task-compile-20250107-123456

# Cleanup
bun ~/.pi/agent/skills/tmux/lib.ts kill pi-task-compile-20250107-123456
```

### Long-running Tasks
Run tasks in the background and check progress later:

```bash
# Start training
bun ~/.pi/agent/skills/tmux/lib.ts create training "python train.py --epochs 100" task

# Check progress later
bun ~/.pi/agent/skills/tmux/lib.ts list
bun ~/.pi/agent/skills/tmux/lib.ts capture pi-task-training-20250107-123456
```

### Service Management
Start development servers or services:

```bash
# Start dev server
bun ~/.pi/agent/skills/tmux/lib.ts create dev-server "npm run dev" service

# Monitor logs
tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t pi-service-dev-server-20250107-123456

# Stop when done
bun ~/.pi/agent/skills/tmux/lib.ts kill pi-service-dev-server-20250107-123456
```

### Interactive Tools
Use interactive tools like Python REPL, gdb, or databases:

```bash
# Python REPL (always use PYTHON_BASIC_REPL=1)
bun ~/.pi/agent/skills/tmux/lib.ts create python "PYTHON_BASIC_REPL=1 python3 -q" task

# Send commands
bun ~/.pi/agent/skills/tmux/lib.ts send pi-task-python-20250107-123456 "print('Hello')"
bun ~/.pi/agent/skills/tmux/lib.ts send pi-task-python-20250107-123456 "2 + 2"
```

## Status Detection

Sessions have three possible states:
- **running**: Process is active with recent output
- **idle**: Process exists but no recent output
- **exited**: Process has terminated

Status is automatically synced with tmux actual state.

## Automatic Cleanup

By default, sessions inactive for more than 24 hours are automatically cleaned up. You can:

- Trigger manual cleanup:
  ```bash
  bun ~/.pi/agent/skills/tmux/lib.ts cleanup [hours]
  ```

- Disable auto-cleanup in code:
  ```typescript
  const tmux = new TmuxManager({ autoCleanup: false });
  ```

## Helper Scripts

### wait-for-text.sh
Polls a pane for a regex pattern with timeout.

```bash
./scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
```

- `-t/--target`: Pane target (required)
- `-p/--pattern`: Regex to match (required); add `-F` for fixed string
- `-T`: Timeout in seconds (default: 15)
- `-i`: Poll interval in seconds (default: 0.5)
- `-l`: History lines to search (default: 1000)

### find-sessions.sh
Lists tmux sessions with metadata.

```bash
./scripts/find-sessions.sh -S "$SOCKET"
./scripts/find-sessions.sh --all  # Scan all sockets
```

## Examples

See the `examples/` directory for complete examples:
- `python-repl.ts`: Interactive Python REPL
- `long-task.ts`: Long-running task with progress
- `start-service.ts`: Service management

## TypeScript API

You can also use the TypeScript API directly:

```typescript
import { TmuxManager } from "~/.pi/agent/skills/tmux/lib.ts";

const tmux = new TmuxManager();

// Create session
const session = await tmux.createSession('compile', 'make all', 'task');

// Wait for output
const success = await tmux.waitForText(session.target, 'Build successful', { timeout: 60 });

// Capture output
const output = await tmux.capturePane(session.target, 200);

// Cleanup
await tmux.killSession(session.id);
```

## Monitoring Sessions

After creating a session, ALWAYS tell the user how to monitor it:

```
To monitor this session yourself:
  tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t pi-task-compile-20250107-123456

Or to capture the output once:
  tmux -S /tmp/pi-tmux-sockets/pi.sock capture-pane -p -J -t pi-task-compile-20250107-123456:0.0 -S -200
```

This must be printed immediately after session creation and at the end of the tool loop.

## Security Considerations

- Uses private socket path to avoid conflicts
- Sends keys in literal mode (`-l`) to prevent shell injection
- Checks tmux actual state before cleanup
- Requires explicit confirmation for destructive operations

## Troubleshooting

### Session not found
Run sync to update session state:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts sync
```

### Cannot attach to session
Ensure tmux is installed and the socket path is correct:
```bash
tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t <session-id>
```

### Sessions not cleaning up
Manually trigger cleanup:
```bash
bun ~/.pi/agent/skills/tmux/lib.ts cleanup
```

### Permission denied on socket
Check socket directory permissions:
```bash
ls -la /tmp/pi-tmux-sockets/
```

## Requirements

- tmux (Linux/macOS)
- Bun runtime
- Bash (for helper scripts)

---

## Referenced Files

> The following files are referenced in this skill and included for context.

### TUI.md

```markdown
# Tmux TUI 管理工具/Manager

交互式终端用户界面（TUI）用于管理 tmux sessions。

## 快速开始/Quick Start

```bash
# 启动 TUI/Launch TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# 或者先创建测试会话/Or create test sessions first
bun ~/.pi/agent/skills/tmux/test-tui.ts
bun ~/.pi/agent/skills/tmux/tui.ts
```

## 键盘快捷键/Keyboard Shortcuts

| 快捷键/Shortcut | 功能/Function |
|-----------------|---------------|
| `↑/↓` | 导航会话列表/Navigate sessions |
| `r` | 刷新会话列表/Refresh sessions |
| `n` | 创建新会话/Create new session |
| `c` | 捕获选中会话的输出/Capture output |
| `s` | 显示选中会话的详细状态/Show status |
| `a` | 显示 attach 命令/Show attach command |
| `k` | 终止选中会话（需要确认）/Kill session (confirm) |
| `q` / `Esc` | 退出 TUI/Exit TUI |

## 创建会话流程/Create Session Flow

1. 按 `n` 进入创建模式/Press `n` to enter create mode
2. 输入会话名称，按 Enter 继续/Enter name, press Enter to continue
3. 输入命令，按 Enter 继续/Enter command, press Enter to continue
4. 输入分类（task/service/agent），按 Enter 创建/Enter category, press Enter to create
5. 自动返回会话列表/Auto-return to session list

## 界面说明/UI Description

### 会话列表/Session List

```
Tmux 会话管理器/Session Manager                   自动刷新/Auto-refresh: 5秒/s

会话ID/Session ID               名称/Name  分类/Category 状态/Status  最后活动/Last Activity
───────────────────────────────────────────────────────────────────────────────────
pi-task-compile-20260109-123456 compile   任务/Task   运行中/Running  0m ago
pi-service-dev-server-20260109-123456 dev-server 服务/Service 运行中/Running  5m ago
```

### 颜色编码/Color Coding

- **状态颜色/Status Colors**：
  - 🟢 `运行中/Running` - 会话正在运行/Session is running
  - 🟡 `空闲/Idle` - 会话空闲/Session is idle
  - 🔴 `已退出/Exited` - 会话已退出/Session has exited

- **分类颜色/Category Colors**：
  - 🔵 `任务/Task` - 临时任务/Temporary tasks
  - 🟣 `服务/Service` - 长期服务/Long-running services
  - 🟦 `代理/Agent` - Agent 任务/Agent-specific tasks

### 创建会话界面/Create Session Interface

```
创建新会话/Create New Session

名称/Name: my-task
命令/Command: echo "Hello World"
分类/Category: task (任务/服务/代理/Task/Service/Agent)

按 Enter 继续/Press Enter to continue，按 Esc 取消/Press Esc to cancel

> my-task█
```

### 捕获输出界面/Capture Output Interface

```
捕获输出/Capture Output

pi-task-compile-20260109-123456

Building...
Compiling main.c...
Linking...
Build successful!

按 Esc 返回/Press Esc to return
```

### 状态详情界面/Status Detail Interface

```
会话状态/Session Status

ID/会话ID: pi-task-compile-20260109-123456
名称/Name: compile
分类/Category: task
状态/Status: running
创建时间/Created: 2026-01-09T12:34:56Z
最后活动/Last Activity: 2026-01-09T12:35:00Z
命令/Command: make all

按 Esc 返回/Press Esc to return
```

### 连接命令界面/Attach Command Interface

```
连接命令/Attach Command

pi-task-compile-20260109-123456

要连接到此会话，请运行/To attach to this session, run:

  tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t pi-task-compile-20260109-123456

断开连接/Detach with: Ctrl+b d

按 Esc 返回/Press Esc to return
```

### 确认删除界面/Confirm Kill Interface

```
确认终止/Confirm Kill

确定要终止以下会话吗？/Are you sure you want to kill session:
  pi-task-compile-20260109-123456

[Y]是/Yes  [N]否/No
```

## 使用示例/Usage Examples

### 管理开发服务器/Manage Development Server

```bash
# 启动 TUI/Launch TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# 按 'n' 创建新会话/Press 'n' to create new session
# 名称/Name: dev-server
# 命令/Command: npm run dev
# 分类/Category: service

# 按 'c' 捕获输出查看日志/Press 'c' to capture output and view logs
# 按 'a' 获取 attach 命令进行交互式操作/Press 'a' to get attach command for interactive access
# 按 'k' 停止服务器/Press 'k' to stop server
```

### 监控编译任务/Monitor Compilation Task

```bash
# 启动 TUI/Launch TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# 按 'n' 创建编译任务/Press 'n' to create compilation task
# 名称/Name: compile
# 命令/Command: make all
# 分类/Category: task

# 按 'c' 捕获输出查看编译进度/Press 'c' to capture output and view compilation progress
# 按 'r' 刷新状态/Press 'r' to refresh status
# 编译完成后按 'k' 清理会话/Press 'k' to cleanup after compilation
```

### 批量管理会话/Bulk Manage Sessions

```bash
# 启动 TUI/Launch TUI
bun ~/.pi/agent/skills/tmux/tui.ts

# 使用 ↑/↓ 导航会话列表/Use ↑/↓ to navigate session list
# 按 's' 查看每个会话的详细状态/Press 's' to view detailed status of each session
# 按 'k' 清理不需要的会话/Press 'k' to cleanup unwanted sessions
# 按 'r' 刷新确保状态同步/Press 'r' to refresh and ensure status sync
```

## 技术细节/Technical Details

### 依赖/Dependencies

- `[email protected]` - React TUI 框架/Framework
- `[email protected]` - React 核心库/Core library
- `@types/[email protected]` - React 类型定义/Type definitions

### 自动刷新/Auto-refresh

TUI 每 5 秒自动刷新会话状态，确保显示最新的会话信息。你也可以按 `r` 手动刷新。
TUI auto-refreshes session status every 5 seconds to ensure latest information. You can also press `r` to manually refresh.

### 数据同步/Data Synchronization

TUI 通过 `TmuxManager` 类与 tmux 通信，确保数据一致性。所有操作都会同步到会话存储文件。
TUI communicates with tmux via `TmuxManager` class, ensuring data consistency. All operations are synchronized to the session storage file.

## 故障排除/Troubleshooting

### TUI 无法启动/TUI Cannot Launch

确保在交互式终端中运行 TUI：
Ensure TUI is running in an interactive terminal:

```bash
# ✅ 正确/Correct: 在终端中运行/Run in terminal
bun ~/.pi/agent/skills/tmux/tui.ts

# ❌ 错误/Error: 通过管道或重定向运行/Run through pipe or redirection
echo "" | bun ~/.pi/agent/skills/tmux/tui.ts
```

### 会话列表为空/Session List Empty

1. 按下 `r` 刷新会话列表/Press `r` to refresh session list
2. 检查 tmux 是否正常运行/Check if tmux is running: `tmux -V`
3. 检查 socket 路径/Check socket path: `ls -la /tmp/pi-tmux-sockets/`

### 键盘无响应/Keyboard Not Responding

1. 确保在交互式终端中运行/Ensure running in interactive terminal
2. 尝试按 `q` 或 `Esc` 退出/Try pressing `q` or `Esc` to exit
3. 重新启动 TUI/Restart TUI

## 相关文档/Related Documentation

- [tmux Skill 文档/Documentation](SKILL.md)
- [lib.ts API 文档/API Documentation](lib.ts)
- [types/index.ts](types/index.ts)
```

### scripts/wait-for-text.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage: wait-for-text.sh -t target -p pattern [options]

Poll a tmux pane for text and exit when found.

Options:
  -t, --target    tmux target (session:window.pane), required
  -p, --pattern   regex pattern to look for, required
  -F, --fixed     treat pattern as a fixed string (grep -F)
  -T, --timeout   seconds to wait (integer, default: 15)
  -i, --interval  poll interval in seconds (default: 0.5)
  -l, --lines     number of history lines to inspect (integer, default: 1000)
  -h, --help      show this help
USAGE
}

target=""
pattern=""
grep_flag="-E"
timeout=15
interval=0.5
lines=1000

while [[ $# -gt 0 ]]; do
  case "$1" in
    -t|--target)   target="${2-}"; shift 2 ;;
    -p|--pattern)  pattern="${2-}"; shift 2 ;;
    -F|--fixed)    grep_flag="-F"; shift ;;
    -T|--timeout)  timeout="${2-}"; shift 2 ;;
    -i|--interval) interval="${2-}"; shift 2 ;;
    -l|--lines)    lines="${2-}"; shift 2 ;;
    -h|--help)     usage; exit 0 ;;
    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
  esac
done

if [[ -z "$target" || -z "$pattern" ]]; then
  echo "target and pattern are required" >&2
  usage
  exit 1
fi

if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
  echo "timeout must be an integer number of seconds" >&2
  exit 1
fi

if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
  echo "lines must be an integer" >&2
  exit 1
fi

if ! command -v tmux >/dev/null 2>&1; then
  echo "tmux not found in PATH" >&2
  exit 1
fi

# End time in epoch seconds (integer, good enough for polling)
start_epoch=$(date +%s)
deadline=$((start_epoch + timeout))

while true; do
  # -J joins wrapped lines, -S uses negative index to read last N lines
  pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"

  if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
    exit 0
  fi

  now=$(date +%s)
  if (( now >= deadline )); then
    echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
    echo "Last ${lines} lines from $target:" >&2
    printf '%s\n' "$pane_text" >&2
    exit 1
  fi

  sleep "$interval"
done

```

### scripts/find-sessions.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]

List tmux sessions on a socket (default tmux socket if none provided).

Options:
  -L, --socket       tmux socket name (passed to tmux -L)
  -S, --socket-path  tmux socket path (passed to tmux -S)
  -A, --all          scan all sockets under CLAUDE_TMUX_SOCKET_DIR
  -q, --query        case-insensitive substring to filter session names
  -h, --help         show this help
USAGE
}

socket_name=""
socket_path=""
query=""
scan_all=false
socket_dir="${CLAUDE_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/claude-tmux-sockets}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    -L|--socket)      socket_name="${2-}"; shift 2 ;;
    -S|--socket-path) socket_path="${2-}"; shift 2 ;;
    -A|--all)         scan_all=true; shift ;;
    -q|--query)       query="${2-}"; shift 2 ;;
    -h|--help)        usage; exit 0 ;;
    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
  esac
done

if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
  echo "Cannot combine --all with -L or -S" >&2
  exit 1
fi

if [[ -n "$socket_name" && -n "$socket_path" ]]; then
  echo "Use either -L or -S, not both" >&2
  exit 1
fi

if ! command -v tmux >/dev/null 2>&1; then
  echo "tmux not found in PATH" >&2
  exit 1
fi

list_sessions() {
  local label="$1"; shift
  local tmux_cmd=(tmux "$@")

  if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
    echo "No tmux server found on $label" >&2
    return 1
  fi

  if [[ -n "$query" ]]; then
    sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
  fi

  if [[ -z "$sessions" ]]; then
    echo "No sessions found on $label"
    return 0
  fi

  echo "Sessions on $label:"
  printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
    attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
    printf '  - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
  done
}

if [[ "$scan_all" == true ]]; then
  if [[ ! -d "$socket_dir" ]]; then
    echo "Socket directory not found: $socket_dir" >&2
    exit 1
  fi

  shopt -s nullglob
  sockets=("$socket_dir"/*)
  shopt -u nullglob

  if [[ "${#sockets[@]}" -eq 0 ]]; then
    echo "No sockets found under $socket_dir" >&2
    exit 1
  fi

  exit_code=0
  for sock in "${sockets[@]}"; do
    if [[ ! -S "$sock" ]]; then
      continue
    fi
    list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
  done
  exit "$exit_code"
fi

tmux_cmd=(tmux)
socket_label="default socket"

if [[ -n "$socket_name" ]]; then
  tmux_cmd+=(-L "$socket_name")
  socket_label="socket name '$socket_name'"
elif [[ -n "$socket_path" ]]; then
  tmux_cmd+=(-S "$socket_path")
  socket_label="socket path '$socket_path'"
fi

list_sessions "$socket_label" "${tmux_cmd[@]:1}"

```