4b4a32eff6
- plugins/tmux-panes.ts: opencode plugin that hooks into session.created/ session.deleted events to spawn a tmux pane per subagent running 'opencode attach', giving live visual TUI for each background agent - opencode.jsonc: load the local plugin alongside @tarquinen/opencode-dcp - skills/tmux-session/SKILL.md: teach agents to manage persistent tmux sessions (dev servers, watchers, worktree windows) with oc- naming - c.fish / cc.fish: auto-start a tmux session when invoked outside tmux so the visual panes plugin can always activate
101 lines
2.9 KiB
Markdown
101 lines
2.9 KiB
Markdown
---
|
|
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
|
|
```
|