feat: add tmux integration with visual subagent panes

- 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
This commit is contained in:
alex
2026-03-11 12:12:24 +00:00
parent 796d36a138
commit 4b4a32eff6
5 changed files with 185 additions and 5 deletions

View File

@@ -0,0 +1,100 @@
---
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
```