Autorun tmux-automation

Complete CLI testing automation using tmux/byobu sessions with ai-monitor integration. Create automated workflows for testing plugins, CLIs, and terminal applications. Includes session management, keystroke control, output capture, and autonomous monitoring capabilities.

install

source · Clone the upstream repo

git clone https://github.com/ahundt/autorun

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ahundt/autorun "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/autorun/skills/tmux-automation" ~/.claude/skills/ahundt-autorun-tmux-automation && rm -rf "$T"

manifest: plugins/autorun/skills/tmux-automation/SKILL.md

source content

Automated CLI Testing with Session Management

This skill provides comprehensive capabilities for automated testing of CLI applications, plugins, and terminal workflows using tmux/byobu sessions with full ai-monitor integration. Perfect for testing Claude Code plugins, command-line tools, and automated workflows.

Core Commands

Session Management

```
byobu new-session -d -s <session-name>
```
- Create new detached session
```
byobu list-sessions
```
- List all active sessions
```
byobu attach-session -t <session-name>
```
- Attach to existing session
```
byobu detach-session
```
- Detach from session (F6)
```
byobu kill-session -t <session-name>
```
- Terminate session
```
tmux list-sessions
```
- List tmux sessions

Window Management

```
byobu new-window -t <session-name>
```
- Create new window
```
byobu list-windows -t <session-name>
```
- List windows in session

byobu kill-window -t <session-name>:<window-index>

- Kill specific window

byobu select-window -t <session-name>:<window-index>

- Select window

Input and Output Control

byobu send-keys -t <session-name> <keys>

- Send keystrokes to window

```
byobu send-keys -t <session-name> C-m
```
- Send Enter/Return key
```
byobu send-keys -t <session-name> C-c
```
- Send Ctrl+C interrupt
```
byobu capture-pane -t <session-name>
```
- Capture window output

byobu capture-pane -t <session-name> -p -S -<lines>

- Capture last N lines

Tmux Commands (direct)

```
tmux new-session -d -s <session-name>
```
- Create new detached tmux session
```
tmux list-sessions
```
- List all tmux sessions
```
tmux attach-session -t <session-name>
```
- Attach to tmux session
```
tmux detach
```
- Detach from tmux session

Specific Keystroke Commands

Control Sequences

```
C-c
```
- Ctrl+C (interrupt/stop current command)
```
C-m
```
- Ctrl+M (Enter/Return)
```
C-d
```
- Ctrl+D (EOF/end of input)
```
C-l
```
- Ctrl+L (clear screen)
```
C-a
```
- Ctrl+A (tmux prefix, then command)
```
C-z
```
- Ctrl+Z (suspend current process)
```
Tab
```
- Tab completion
```
Esc
```
- Escape key

Byobu Specific Keys

```
F2
```
- Create new window
```
Shift+F2
```
- Split window horizontally
```
Ctrl+F2
```
- Split window vertically
```
F3
```
- Previous window
```
F4
```
- Next window
```
F5
```
- Reload profile
```
F6
```
- Detach session
```
F7
```
- Search scrollback buffer
```
F8
```
- Enter scrollback mode
```
F9
```
- Configure byobu
```
Shift+F3
```
/
```
Shift+F4
```
- Move window left/right
```
Ctrl+F3
```
/
```
Ctrl+F4
```
- Focus pane left/right

Tmux Prefix Commands (default Ctrl+B)

```
Ctrl+B c
```
- Create new window
```
Ctrl+B &
```
- Kill current window
```
Ctrl+B ,
```
- Rename window
```
Ctrl+B n
```
- Next window
```
Ctrl+B p
```
- Previous window
```
Ctrl+B %
```
- Split window horizontally
```
Ctrl+B "
```
- Split window vertically
```
Ctrl+B o
```
- Switch panes
```
Ctrl+B d
```
- Detach session
```
Ctrl+B s
```
- List sessions

AI-Monitor Integration

The ai_monitor.py in autorun provides comprehensive tmux monitoring and automation:

Core AI-Monitor Functions

# Start monitoring a session
start_monitor(session_id, prompt="Continue working", stop_marker="COMPLETE", max_cycles=5)

# Stop monitoring
stop_monitor(session_id)

# Check if monitor is running
check_monitor(session_id)

AI-Monitor Capabilities

Session Discovery: Automatically finds tmux sessions and windows
Content Monitoring: Tracks window content changes and detects meaningful updates
Change Detection: Filters out minor changes (echoes) vs. substantial content updates
Automatic Re-prompting: Sends continuation prompts when idle (configurable intervals)
Stop Marker Detection: Automatically stops when specific completion markers appear
Cycle Management: Limits number of re-prompt cycles to prevent infinite loops
Window Management: Can target specific windows for monitoring and interaction

autorun Command Integration

autorun provides convenient commands for tmux session automation:

Session Discovery

```
/ar:tabs
```
- Discover and manage all Claude sessions across tmux windows
- Interactive table showing session status (working, awaiting input, etc.)
- Batch operations:
```
all:continue
```
  ,
```
awaiting:status
```
  ,
```
A:pwd, B:ls
```
- AI-powered session analysis (uses Claude SDK when available)

Session Management

```
/ar:tmux
```
or
```
/ar:tm
```
- Create and manage isolated tmux sessions
- ```
create <name>
```
  - Create new isolated session
- ```
list
```
  - List all sessions with health status
- ```
cleanup
```
  - Remove sessions older than 1 hour

Testing Automation

```
/ar:ttest
```
or
```
/ar:tt
```
- Automated CLI testing in isolated sessions
- Tests basic functionality, help system, custom commands
- 30-second timeout protection
- Clean session isolation

Quick Reference: Commands vs Manual tmux

Task	Manual tmux Command	autorun Shortcut
List Claude sessions	`tmux list-windows` (manual)	`/ar:tabs`
Create session	`tmux new-session -d -s name`	`/ar:tm create name`
Send to all sessions	`for s in $(tmux list-sessions); do ...`	`/ar:tabs all:continue`
Test CLI	Manual scripting required	`/ar:tt test my-cli`

AI-Monitor Configuration Options

```
--prompt/-p <text>
```
- Custom prompt to send when idle
```
--stop/-s <string>
```
- Stop marker to detect completion
```
--stop-delay-seconds <n>
```
- Delay before stopping after detecting stop marker
```
--max-retry-cycles/-c <n>
```
- Maximum number of re-prompt cycles
```
--max-runtime-minutes <n>
```
- Maximum runtime in minutes
```
--check-interval <n>
```
- Seconds between checks
```
--prompt-on-start
```
- Send prompt immediately on start
```
--start <window_numbers>
```
- Target specific windows

Usage Examples

Create Testing Session with AI-Monitor

# Create session (default: autorun)
byobu new-session -d -s "autorun"

# Navigate and start process
byobu send-keys -t "autorun" "cd /path/to/project" C-m
byobu send-keys -t "autorun" "npm test" C-m

# Start ai-monitor (from separate terminal)
python3 ai_monitor.py "autorun" --prompt "Continue testing" --stop "Tests completed" --max-cycles 3

Monitor Claude Code Session

# Create Claude Code session (default: autorun unless user specifies otherwise)
byobu new-session -d -s "autorun"
byobu send-keys -t "autorun" "cd /project" C-m
byobu send-keys -t "autorun" "claude" C-m

# Start monitoring for autonomous work
python3 ai_monitor.py "autorun" --prompt "Continue working autonomously" --stop "AUTORUN_ALL_TASKS_COMPLETED" --max-cycles 10

Automated Plugin Testing Workflow

# Create session for autorun testing (default: autorun)
byobu new-session -d -s "autorun"

# Navigate to project (replace with your autorun directory)
byobu send-keys -t "autorun" "cd \$HOME/.claude/autorun" C-m

# Start Claude Code
byobu send-keys -t "autorun" "claude" C-m
sleep 5

# Set model to haiku for efficiency
byobu send-keys -t "autorun" "/model haiku" C-m
sleep 2

# Install plugin locally (replace with your autorun directory)
byobu send-keys -t "autorun" "/plugin marketplace add \$HOME/.claude/autorun" C-m
sleep 3

# Install plugin
byobu send-keys -t "autorun" "/plugin install autorun@autorun" C-m
sleep 5

# Test commands
byobu send-keys -t "autorun" "/afs" C-m
sleep 3

byobu send-keys -t "autorun" "/afst" C-m
sleep 3

# Capture output for verification
byobu capture-pane -t "autorun" -p -S -20

Error Handling and Recovery

# Check if session exists before operations
if byobu list-sessions | grep -q "test-session"; then
    echo "Session exists, proceeding..."
else
    echo "Session not found, creating..."
    byobu new-session -d -s "test-session"
fi

# Interrupt hanging commands
byobu send-keys -t "test-session" C-c

# Kill and recreate session if needed
byobu kill-session -t "test-session"
byobu new-session -d -s "test-session"

Common Mistakes and Solutions

CRITICAL: Control Sequence Syntax Errors

❌ Common Mistake: Incorrect Enter Key Syntax

# WRONG - This will NOT work as expected
byobu send-keys -t "session_name" "command" "C-m"  # WRONG syntax
byobu send-keys -t "session_name" "command C-m"     # WRONG syntax

✅ CORRECT: Proper Control Sequence Syntax

# CORRECT - Each operation is ALWAYS a separate byobu send-keys command
byobu send-keys -t "session_name" "command"   # Step 1: Type the command text
byobu send-keys -t "session_name" C-m         # Step 2: Press Enter to execute

byobu send-keys -t "session_name" "cd /path"  # Step 1: Type "cd /path"
byobu send-keys -t "session_name" C-m         # Step 2: Press Enter to execute

# EFFICIENCY TIP: Chain operations with && for single-line execution
byobu send-keys -t "session_name" C-c && byobu send-keys -t "session_name" C-m  # Interrupt + confirm

byobu send-keys -t "session_name" C-c         # Step 1: Press Ctrl+C interrupt
byobu send-keys -t "session_name" C-m         # Step 2: Press Enter to confirm (if needed)

Key Rules:

Control sequences (C-m, C-c, C-d) must be separate arguments, not inside quotes
Commands go in quotes, control sequences go outside quotes as separate args
```
C-m
```
= Enter/Return,
```
C-c
```
= Ctrl+C,
```
C-d
```
= EOF,
```
C-l
```
= Clear screen
CRITICAL: Text input and Enter key are ALWAYS separate byobu send-keys operations
CRITICAL: Enter key (C-m) must ALWAYS be sent as a separate operation after typing text
CRITICAL: Ctrl+C (C-c) and Enter (C-m) are different operations and must be sent separately when needed

Command Execution Issues

Problem: Commands appear to execute but fail silently

Cause: Missing proper Enter key sequence (C-m)
Solution: Always add
```
C-m
```
as separate argument after command

Problem: Commands hang or timeout

Cause: Missing sleep intervals for Claude Code processing
Solution: Add
```
sleep 2-5
```
between commands, especially after Claude Code startup

Problem: Session becomes unresponsive

Cause: Commands failing without proper error handling
Solution: Use Ctrl+C (
```
C-c
```
) to interrupt, recreate session if needed

Plugin Installation Issues

Problem: Marketplace addition fails with "not found"

Cause: Incorrect path syntax or marketplace already exists
Solution: Use absolute paths and check existing marketplaces first

Problem: Plugin installation fails after marketplace addition

Cause: Timing issues or plugin name mismatch
Solution: Wait for marketplace addition to complete, use correct plugin identifier

Discovery: Slash Commands vs Plugin Installation

Some functionality may be installed as slash commands in
```
~/.claude/commands/
```
rather than formal plugins
Check slash commands first:
```
ls -la ~/.claude/commands/
```
Slash commands work immediately without plugin installation
Example:
```
/afs
```
,
```
/afst
```
,
```
/afa
```
,
```
/afj
```
may be available as slash commands even when no plugins are installed

Best Practices

Session Naming: Always use "autorun" as the default session name unless user specifies another tmux session name
Default Session: Use "autorun" as the default session name for all autorun testing workflows
Existence Checks: Always verify session existence before operations using
```
byobu list-sessions
```
Error Recovery: Implement Ctrl+C handling for stuck commands and session recreation when needed
Output Verification: Use capture-pane for command result verification and testing validation
Resource Management: Clean up sessions after testing with
```
byobu kill-session
```
Timing: Add appropriate sleep intervals between commands (2-5 seconds for Claude Code startup)
AI-Monitor Integration: Use ai-monitor for long-running autonomous sessions and automated workflows
Model Selection: Use haiku for automated tasks to reduce resource usage and improve performance
Byobu vs Tmux: Prefer byobu commands for user-friendly interface, tmux commands for scripting
Control Sequences: Always use proper control sequence syntax - commands in quotes, C-m/C-c as separate arguments
Error Prevention: Test control sequences manually before automation scripts
Efficiency Operations: Use
```
&&
```
to chain byobu commands for single-line execution:
```
byobu send-keys C-c && byobu send-keys C-m
```
Debugging Strategy: Test functionality step-by-step instead of assuming installation state
Slash Command Priority: Check
```
~/.claude/commands/
```
first before plugin installation attempts

Implementation Notes

This skill uses tmux as the primary backend (byobu is a tmux wrapper providing user-friendly interface)
Byobu provides enhanced F-key shortcuts and session management over tmux
All tmux commands work with both byobu and tmux sessions (byobu with tmux backend)
AI-monitor provides the automation layer for autonomous workflows and session monitoring
Control sequences (C-m for Enter, C-c for interrupt) are critical for proper command execution
Proper timing and error handling ensure reliable automated testing workflows
Byobu sessions can be managed with both byobu commands and direct tmux commands

External Resources and References

Documentation Links

Byobu Official Documentation - https://www.byobu.org/
- Use when learning byobu-specific features and configuration
- Essential for understanding F-key shortcuts and byobu workflow
- Visit when setting up new byobu environments
Tmux Manual - https://github.com/tmux/tmux/wiki
- Reference for advanced tmux commands and scripting
- Use when creating complex session automation scripts
- Essential for understanding tmux prefix commands and scripting
Claude Code Skills Documentation - https://docs.claude.com/en/docs/claude-code/skills
- Learn how to create and structure Claude Code skills
- Use when creating additional skills or extending this one
- Essential for understanding skill YAML frontmatter and formatting
Claude Code Plugin Documentation - https://docs.claude.com/en/docs/claude-code/plugins
- Reference for Claude Code plugin development
- Use when developing or debugging Claude Code plugins
- Essential for understanding plugin architecture and hook systems
Claude Code Plugin Examples - https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/plugins/README.md
- Official examples and patterns for Claude Code plugins
- Use when implementing plugin features or debugging issues
- Essential for understanding best practices from official plugins

Testing and Automation Resources

AI-Monitor Integration (autorun) -
```
src/autorun/ai_monitor.py
```
- Built-in tmux monitoring and automation capabilities
- Use for autonomous session monitoring and automated re-prompting
- Essential for long-running automated workflows and testing
Bash Scripting Guide - https://www.gnu.org/software/bash/manual/
- Reference for creating automated test scripts
- Use when writing complex test automation scripts
- Essential for proper error handling and process control

When to Use Each Resource

Setup Phase:

Visit Byobu Documentation when first setting up your testing environment
Check Claude Code Skills Documentation when creating new skills
Review tmux Manual when learning advanced session management

Development Phase:

Use AI-Monitor integration for implementing autonomous workflows
Reference Claude Code Plugin Examples when developing plugins
Consult Bash Scripting Guide for complex automation scripts

Debugging Phase:

Check Claude Code Plugin Documentation when troubleshooting plugin issues
Review tmux Manual when debugging session management problems
Use AI-Monitor logs when monitoring automated workflows

Best Practices:

Always reference official Claude Code Plugin Examples for patterns
Keep Byobu Documentation handy for session management shortcuts
Use tmux Manual for scripting complex automation scenarios

Autorun tmux-automation

Automated CLI Testing with Session Management

Core Commands

Session Management

Window Management

Input and Output Control

Tmux Commands (direct)

Specific Keystroke Commands

Control Sequences

Byobu Specific Keys

Tmux Prefix Commands (default Ctrl+B)

AI-Monitor Integration

Core AI-Monitor Functions

AI-Monitor Capabilities

autorun Command Integration

Session Discovery

Session Management

Testing Automation

Related Documentation

Quick Reference: Commands vs Manual tmux

AI-Monitor Configuration Options

Usage Examples

Create Testing Session with AI-Monitor

Monitor Claude Code Session

Automated Plugin Testing Workflow

Error Handling and Recovery

Common Mistakes and Solutions

CRITICAL: Control Sequence Syntax Errors

Command Execution Issues

Plugin Installation Issues

Best Practices

Implementation Notes

External Resources and References

Documentation Links

Testing and Automation Resources

When to Use Each Resource