tmux Skill

Core Concepts

Socket: /tmp/pi-tmux-sockets/pi.sock (private, no conflicts with personal tmux)

Session Naming: pi-{category}-{name}-{timestamp}

• Categories: task (temporary), service (long-running), agent (agent-specific)

Session States: running | idle | exited

Persistence: /tmp/pi-tmux-sessions.json

Auto-cleanup: Inactive sessions > 24h removed (configurable)

CLI Commands

bun ~/.pi/agent/skills/tmux/lib.ts <command>

create <name> <command> [category] # Create session, prints monitoring command list [filter] # List sessions with status status <id> # Session details send <id> <keys> # Send keystrokes (literal mode, safe) capture <id> [lines] # Capture pane output (default: 200) kill <id> # Terminate session cleanup [hours] # Remove old sessions (default: 24h) attach <id> # Print attach command sync # Sync session state with tmux

TUI: bun ~/.pi/agent/skills/tmux/tui.ts (visual management, shortcuts: r/n/c/s/a/k/q)

TypeScript API

import { TmuxManager } from "~/.pi/agent/skills/tmux/lib.ts";

const tmux = new TmuxManager({ autoCleanup: false }); // optional config

// Session lifecycle const session = await tmux.createSession(name, command, category); await tmux.killSession(session.id);

// Output handling const output = await tmux.capturePane(target, lines); const success = await tmux.waitForText(target, pattern, { timeout: 60 });

// State management const sessions = await tmux.listSessions(filter); const status = await tmux.getSessionStatus(id); await tmux.sync(); await tmux.cleanup(hours);

Key Rules

Always print monitoring command after session creation:

tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t {session-id}

Use send for interactive tools (Python REPL, gdb, databases):

Python REPL: always use PYTHON_BASIC_REPL=1

bun ~/.pi/agent/skills/tmux/lib.ts create python "PYTHON_BASIC_REPL=1 python3 -q" task bun ~/.pi/agent/skills/tmux/lib.ts send pi-task-python-* "print('Hello')"

Category selection:

• task : compilation, testing, temporary operations

• service : dev servers, databases, persistent services

• agent : training, data processing, agent-specific tasks

Safe key injection: send uses literal mode (-l ), no shell escaping needed

Session recovery: Run sync if session not found

Helper Scripts

Wait for text pattern with timeout

./scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]

List sessions with metadata

./scripts/find-sessions.sh -S "$SOCKET" ./scripts/find-sessions.sh --all

Requirements

• tmux (Linux/macOS)

• Bun runtime

• Bash (helper scripts)