tmux

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 runtime installed
• tmux installed (brew install tmux or apt install tmux)

Commands

List Sessions

List all active tmux sessions.

bun .opencode/skill/tmux/list-sessions.js [options]

Options:

• --json - Output as JSON

Examples:

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.

bun .opencode/skill/tmux/create-session.js <name> [options]

Arguments:

• name - Session name (required)

Options:

• --command <cmd> - Initial command to run in the session
• --workdir <path> - Working directory for the session
• --window <name> - Name for the initial window
• --json - Output as JSON

Examples:

# 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).

bun .opencode/skill/tmux/send-command.js <session> <command> [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:

# 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.

bun .opencode/skill/tmux/capture-output.js <session> [options]

Arguments:

• session - Session name (or session:window or session:window.pane)

Options:

• --lines <n> - Number of lines of scrollback to capture (default: 100)
• --wait <pattern> - Wait for output matching this pattern before capturing
• --timeout <ms> - Timeout for --wait in milliseconds (default: 30000)
• --json - Output as JSON

Examples:

# 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.

bun .opencode/skill/tmux/kill-session.js <name> [options]

Arguments:

• name - Session name to kill

Options:

• --json - Output as JSON

Examples:

bun .opencode/skill/tmux/kill-session.js db-session

---

Common Workflows

Database Session (psql)

# 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

# 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.)

# 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