Agent skill

tmux

Manage tmux sessions for interactive background processes

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/bind/tmux

SKILL.md

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.

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 <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:

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 <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:

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 <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:

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 <name> [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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results