---
name: tmux-session
description: Manage persistent terminal sessions in tmux for long-running processes, dev servers, and interactive tools — load when a task needs a background process or interactive shell
permalink: opencode-config/skills/tmux-session/skill
---

## When to Use This Skill

Load this skill when a task requires:
- Running a **dev server or watcher** that must stay alive across multiple tool calls (e.g. `npm run dev`, `cargo watch`, `pytest --watch`)
- An **interactive REPL or debugger** that needs to persist state between commands
- Running a process **in the background** while working in the main pane
- **Parallel worktree work** where each feature branch gets its own named window

Do NOT use tmux for one-shot commands that complete and exit — use `bash` directly for those.

## Naming Convention

All opencode-managed sessions and windows use the `oc-` prefix:

| Resource | Name pattern | Example |
|---|---|---|
| Named session | `oc-<project>` | `oc-myapp` |
| Named window | `oc-<feature>` | `oc-auth-refactor` |
| Background process window | `oc-bg-<process>` | `oc-bg-dev-server` |

## Starting a Persistent Session

```bash
# Check if already inside tmux
echo $TMUX

# Start a new named session (detached) for a long-running process
tmux new-session -d -s oc-bg-dev-server "npm run dev"

# Or in a new window within the current session
tmux new-window -n oc-bg-dev-server "npm run dev"
```

## Sending Commands to a Running Session

```bash
# Send a command to a named session
tmux send-keys -t oc-bg-dev-server "npm run build" Enter

# Read the last N lines of output from a pane
tmux capture-pane -t oc-bg-dev-server -p | tail -20
```

## Checking if a Session/Window Exists

```bash
# Check for a named session
tmux has-session -t oc-bg-dev-server 2>/dev/null && echo "running" || echo "not running"

# List all oc- prefixed windows in current session
tmux list-windows -F "#{window_name}" | grep "^oc-"
```

## Worktree + Window Workflow

When working across multiple git worktrees, open each in its own tmux window:

```bash
# Create worktree and open it in a dedicated window
git worktree add .worktrees/auth-refactor -b auth-refactor
tmux new-window -n oc-auth-refactor -c .worktrees/auth-refactor
```

Switch between worktrees by switching windows:
```bash
tmux select-window -t oc-auth-refactor
```

## Cleanup

Always clean up sessions and windows when done:

```bash
# Kill a specific window
tmux kill-window -t oc-bg-dev-server

# Kill a detached session
tmux kill-session -t oc-bg-dev-server

# Kill all oc- prefixed windows in current session
tmux list-windows -F "#{window_name}" | grep "^oc-" | xargs -I{} tmux kill-window -t {}
```

## Checking Process Output

Before assuming a background process is healthy, capture its recent output:

```bash
# Capture last 30 lines of a pane
tmux capture-pane -t oc-bg-dev-server -p -S -30

# Check if process is still running (exit code 0 = alive)
tmux has-session -t oc-bg-dev-server 2>/dev/null
```