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

bash
1bun ~/.pi/agent/skills/tmux/lib.ts <command>
2
3create <name> <command> [category]    # Create session, prints monitoring command
4list [filter]                         # List sessions with status
5status <id>                           # Session details
6send <id> <keys>                      # Send keystrokes (literal mode, safe)
7capture <id> [lines]                  # Capture pane output (default: 200)
8kill <id>                             # Terminate session
9cleanup [hours]                       # Remove old sessions (default: 24h)
10attach <id>                           # Print attach command
11sync                                  # 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

typescript
1import { TmuxManager } from "~/.pi/agent/skills/tmux/lib.ts";
2
3const tmux = new TmuxManager({ autoCleanup: false }); // optional config
4
5// Session lifecycle
6const session = await tmux.createSession(name, command, category);
7await tmux.killSession(session.id);
8
9// Output handling
10const output = await tmux.capturePane(target, lines);
11const success = await tmux.waitForText(target, pattern, { timeout: 60 });
12
13// State management
14const sessions = await tmux.listSessions(filter);
15const status = await tmux.getSessionStatus(id);
16await tmux.sync();
17await tmux.cleanup(hours);

Key Rules

1. Always print monitoring command after session creation:

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

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

   bash
   1# Python REPL: always use PYTHON_BASIC_REPL=1
   2bun ~/.pi/agent/skills/tmux/lib.ts create python "PYTHON_BASIC_REPL=1 python3 -q" task
   3bun ~/.pi/agent/skills/tmux/lib.ts send pi-task-python-* "print('Hello')"

3. Category selection:

   • task: compilation, testing, temporary operations
   • service: dev servers, databases, persistent services
   • agent: training, data processing, agent-specific tasks

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

5. Session recovery: Run sync if session not found

Helper Scripts

bash
1# Wait for text pattern with timeout
2./scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
3
4# List sessions with metadata
5./scripts/find-sessions.sh -S "$SOCKET"
6./scripts/find-sessions.sh --all

Requirements

• tmux (Linux/macOS)
• Bun runtime
• Bash (helper scripts)