--- name: tmux description: Manage tmux sessions for interactive background processes version: 1.0.0 license: MIT compatibility: opencode --- ## Overview CLI tools for managing tmux sessions, enabling agents to run and interact with background processes like database connections (psql, mysql), REPLs, log tailing, and other interactive commands. ## Prerequisites - [bun](https:\/\/bun.sh) runtime installed - [tmux](https:\/\/github.com\/tmux\/tmux) installed (`brew install tmux` or `apt install tmux`) ## Commands ### List Sessions List all active tmux sessions. ```bash bun .opencode\/skill\/tmux\/list-sessions.js [options] ``` **Options:** - `--json` - Output as JSON **Examples:** ```bash bun .opencode\/skill\/tmux\/list-sessions.js bun .opencode\/skill\/tmux\/list-sessions.js --json ``` --- ### Create Session Create a new tmux session for running background processes. ```bash bun .opencode\/skill\/tmux\/create-session.js [options] ``` **Arguments:** - `name` - Session name (required) **Options:** - `--command ` - Initial command to run in the session - `--workdir ` - Working directory for the session - `--window ` - Name for the initial window - `--json` - Output as JSON **Examples:** ```bash # Create a session for psql bun .opencode\/skill\/tmux\/create-session.js db-session --command "psql -h localhost -U postgres mydb" # Create a session for tailing logs bun .opencode\/skill\/tmux\/create-session.js logs --command "tail -f \/var\/log\/app.log" # Create a session in a specific directory bun .opencode\/skill\/tmux\/create-session.js dev --workdir ~\/projects\/myapp ``` --- ### Send Command Send a command to a tmux session (types the command and presses Enter). ```bash bun .opencode\/skill\/tmux\/send-command.js [options] ``` **Arguments:** - `session` - Session name (or session:window or session:window.pane) - `command` - Command to send **Options:** - `--no-enter` - Send keys without pressing Enter - `--literal` - Send keys literally (no special key interpretation) - `--json` - Output as JSON **Examples:** ```bash # Run a SQL query in a psql session bun .opencode\/skill\/tmux\/send-command.js db-session "SELECT * FROM users LIMIT 10;" # Send Ctrl+C to interrupt a process bun .opencode\/skill\/tmux\/send-command.js logs "C-c" --no-enter # Type text without executing bun .opencode\/skill\/tmux\/send-command.js dev "echo hello" --no-enter ``` --- ### Capture Output Capture and read the current output from a tmux session pane. ```bash bun .opencode\/skill\/tmux\/capture-output.js [options] ``` **Arguments:** - `session` - Session name (or session:window or session:window.pane) **Options:** - `--lines ` - Number of lines of scrollback to capture (default: 100) - `--wait ` - Wait for output matching this pattern before capturing - `--timeout ` - Timeout for --wait in milliseconds (default: 30000) - `--json` - Output as JSON **Examples:** ```bash # Capture recent output from a session bun .opencode\/skill\/tmux\/capture-output.js db-session # Capture more scrollback history bun .opencode\/skill\/tmux\/capture-output.js logs --lines 500 # Wait for a specific prompt before capturing bun .opencode\/skill\/tmux\/capture-output.js db-session --wait "postgres=#" --timeout 5000 ``` --- ### Kill Session Terminate a tmux session. ```bash bun .opencode\/skill\/tmux\/kill-session.js [options] ``` **Arguments:** - `name` - Session name to kill **Options:** - `--json` - Output as JSON **Examples:** ```bash bun .opencode\/skill\/tmux\/kill-session.js db-session ``` --- ## Common Workflows ### Database Session (psql) ```bash # Create a psql session bun .opencode\/skill\/tmux\/create-session.js psql --command "psql -h localhost -U postgres mydb" # Wait for connection, then run queries bun .opencode\/skill\/tmux\/capture-output.js psql --wait "postgres=#" bun .opencode\/skill\/tmux\/send-command.js psql "SELECT COUNT(*) FROM users;" # Capture the query results bun .opencode\/skill\/tmux\/capture-output.js psql --lines 50 # Clean up when done bun .opencode\/skill\/tmux\/kill-session.js psql ``` ### Log Monitoring ```bash # Start tailing logs bun .opencode\/skill\/tmux\/create-session.js logs --command "tail -f \/var\/log\/app.log" # Check for errors periodically bun .opencode\/skill\/tmux\/capture-output.js logs --lines 200 # Stop monitoring bun .opencode\/skill\/tmux\/kill-session.js logs ``` ### Interactive REPL (Python, Node, etc.) ```bash # Start a Python REPL bun .opencode\/skill\/tmux\/create-session.js python --command "python3" # Run Python commands bun .opencode\/skill\/tmux\/send-command.js python "import pandas as pd" bun .opencode\/skill\/tmux\/send-command.js python "df = pd.read_csv('data.csv')" bun .opencode\/skill\/tmux\/send-command.js python "df.describe()" # Capture output bun .opencode\/skill\/tmux\/capture-output.js python ``` --- ## Output Behavior - Command output is displayed directly to the user in the terminal - **Do not re-summarize or reformat output** - the user can already see it - When capturing output, the raw terminal content is returned (may include ANSI codes) - Use `--json` for structured output when parsing programmatically ## Notes - Session names should be descriptive and unique (e.g., `psql-mydb`, `logs-app`) - Target format: `session` or `session:window` or `session:window.pane` - Special keys: `C-c` (Ctrl+C), `C-d` (Ctrl+D), `C-m` (Enter), `C-l` (clear) - Sessions persist until explicitly killed or system restart