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:
100
.config/opencode/skills/tmux-session/SKILL.md
Normal file
100
.config/opencode/skills/tmux-session/SKILL.md
Normal 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
|
||||
```
|
||||
Reference in New Issue
Block a user