gh-shanev-skills-tmux-task-runner/skills/tmux-task-runner

tmux Task Runner

Execute long-running tasks in tmux sessions with real-time monitoring. Tasks run in detached sessions with persistent logging and easy monitoring.

Features

• Detached tmux sessions for long-running tasks
• Persistent logs and status metadata (configurable via LOG_DIR / STATUS_DIR)
• Flexible run options: --workdir, repeatable --env overrides, and optional notifications
• Real-time output monitoring via tmux, the built-in tail helper, or log files
• Session management (list, status, check, attach, kill)
• Clean output optimized for Claude Code

Prerequisites

This skill requires tmux to be installed:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora/RHEL
sudo dnf install tmux

Usage

Once installed, Claude automatically invokes this skill when you request long-running tasks.

Examples:

• You: "Run the test suite in the background"

• Claude: Executes tests in a tmux session with monitoring commands

• You: "Start the build process and let me monitor it"

• Claude: Creates a tmux session with the build command and provides monitoring instructions

Manual Commands

You can also use the run script directly:

# Run a task
./run.sh run build "npm run build"

# Provide a working directory and environment overrides
./run.sh run test --workdir ./services/api --env NODE_ENV=ci --env DEBUG=1 "npm test -- --runInBand"

# Enable notifications when the command finishes (best effort)
./run.sh run deploy --notify "./scripts/deploy.sh production"

# Check status
./run.sh check task-build-1729519263

# List all tasks
./run.sh list

# Summarize recent runs or inspect a specific session
./run.sh status
./run.sh status task-build-1729519263

# Tail output without attaching
./run.sh tail task-build-1729519263 --interval 5 --lines 80

# Attach to session
./run.sh attach task-build-1729519263

# Kill a task
./run.sh kill task-build-1729519263

# Get help
./run.sh help

Use Cases

• Build processes (webpack, npm build, etc.)
• Test suites (jest, pytest, etc.)
• Development servers
• Deployment scripts
• Any command requiring background execution with monitoring

Examples

See EXAMPLES.md for detailed usage examples including:

• CI/CD pipeline simulation
• Running multiple concurrent tasks
• Database migrations
• Load testing
• And more

How It Works

1. Creates a uniquely-named tmux session (e.g., task-build-1729519263)
2. Runs your command in the detached session
3. Captures all output to ${LOG_DIR:-/tmp}/task-{name}.log
4. Provides monitoring commands for real-time output
5. Session persists until task completes or you kill it

Monitoring Sessions

View logs in real-time (LOG_DIR defaults to /tmp):

tail -f "$LOG_DIR"/task-build-1729519263.log

Attach to session interactively:

tmux attach-session -t task-build-1729519263
# Press Ctrl+b then d to detach

Quick output snapshot:

tmux capture-pane -t task-build-1729519263 -p

Poll output without attaching:

./run.sh tail task-build-1729519263 --interval 5 --lines 80

Configuration

Set the following environment variables before invoking run.sh (or exporting them in your shell) to customize behavior:

• LOG_DIR (default /tmp): where log files are written
• STATUS_DIR (default /tmp): stores status metadata for each task
• PRUNE_RETENTION_DAYS (default 7): automatically removes logs/status files older than this many days
• STATUS_SUMMARY_LIMIT (default 10): number of entries shown by list/status
• TAIL_DEFAULT_LINES (default 50): lines captured per refresh by tail
• TAIL_DEFAULT_INTERVAL (default 2): seconds between refreshes in tail

Directories are created automatically if they do not exist.

Troubleshooting

tmux not found: Install tmux using your system package manager (see Prerequisites)

Session closed unexpectedly: Check the log file for errors: cat "$LOG_DIR"/task-{name}.log

Can't find session: List all sessions: tmux list-sessions or ./run.sh list

Too many old sessions: Kill all task sessions: ./run.sh kill all

Task appears hung: Inspect the session with ./run.sh check <session> and kill it if needed: ./run.sh kill <session>