tmux

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