Skip to content

Tmux Actions Tool

Comprehensive tmux session management script for organizing development workflows by role and project.

Features

  • Session Listing: List all tmux sessions or filter by role-based naming conventions
  • Role-Based Filtering: Separate views for Product Manager (PM:) and Engineer (ENG:) sessions
  • Session Creation: Create new sessions with descriptive names and automatic naming validation
  • Log Retrieval: Capture session scrollback buffer for debugging and analysis
  • Session Management: End sessions safely with confirmation prompts
  • Smart Organization: Support for structured naming conventions to organize work contexts

Available Commands

Session Listing

  • list (or ls) - List all active tmux sessions
  • pm - List only Product Manager sessions (containing "PM:" in name)
  • eng - List only Engineer sessions (containing "ENG:" in name)

Session Management

  • create <name> - Create a new tmux session with specified name
  • logs <name> [lines] [file] - Get session logs (default: 100 lines, optionally save to file)
  • end <name> - End/kill a tmux session (with confirmation)
  • help - Display comprehensive usage information

Command Options

  • --silent - Run in silent mode (suppress header output)

Usage Examples

# List all sessions
./docs/actions/tmux-actions.sh list

# List role-specific sessions
./docs/actions/tmux-actions.sh pm
./docs/actions/tmux-actions.sh eng

# Create new sessions
./docs/actions/tmux-actions.sh create "PM: Dashboard Project"
./docs/actions/tmux-actions.sh create "ENG: Backend API"
./docs/actions/tmux-actions.sh create "Testing Environment"

# Get session logs
./docs/actions/tmux-actions.sh logs "PM: Dashboard Project"
./docs/actions/tmux-actions.sh logs "ENG: Backend API" 200
./docs/actions/tmux-actions.sh logs "PM: Dashboard Project" 500 session-logs.txt

# End a session
./docs/actions/tmux-actions.sh end "PM: Dashboard Project"

Naming Conventions

  • Product Manager: PM: <project-name> (e.g., "PM: Dashboard Project")
  • Engineer: ENG: <project-name> (e.g., "ENG: Backend API")
  • General: <descriptive-name> (e.g., "Testing Environment")

Benefits of Structured Naming

  • Quick role-based session filtering
  • Clear project context identification
  • Improved workflow organization
  • Team collaboration clarity

Log Management

Log Capture Options

  • Default Display: Shows last 100 lines in terminal
  • Custom Line Count: Specify number of lines to capture (e.g., 200, 500)
  • File Output: Save logs to file for analysis or sharing
  • Scrollback Buffer: Captures tmux session's scrollback history

Log Use Cases

  • Debugging: Capture error messages and stack traces
  • Progress Tracking: Monitor long-running processes
  • Team Sharing: Export session logs for collaboration
  • Documentation: Save important terminal output for reference

Safety Features

  • Tmux Installation Check: Verifies tmux is installed before execution
  • Session Existence Validation: Checks if sessions exist before operations
  • Confirmation Prompts: Requires confirmation before ending sessions
  • Duplicate Prevention: Warns when creating sessions with existing names
  • Error Handling: Comprehensive error messages and usage guidance

File Location

  • Linux Script: custom-scripts/linux/tmux/tmux-actions.sh

Requirements

  • tmux installed (sudo apt install tmux on Ubuntu/Debian or brew install tmux on macOS)
  • Bash shell environment
  • Read/write permissions for tmux socket directory

Integration Tips

  • Use with IDE workspace switching for complete context management
  • Combine with project-specific environment variables
  • Integrate into daily standup workflows for quick session overview
  • Perfect for managing multiple client projects simultaneously