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
2.9 KiB
2.9 KiB
name, description, permalink
| name | description | permalink |
|---|---|---|
| tmux-session | 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 | 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
# 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
# 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
# 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:
# 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:
tmux select-window -t oc-auth-refactor
Cleanup
Always clean up sessions and windows when done:
# 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:
# 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