155 lines
4.2 KiB
Markdown
155 lines
4.2 KiB
Markdown
# `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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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](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`):**
|
|
```bash
|
|
tail -f "$LOG_DIR"/task-build-1729519263.log
|
|
```
|
|
|
|
**Attach to session interactively:**
|
|
```bash
|
|
tmux attach-session -t task-build-1729519263
|
|
# Press Ctrl+b then d to detach
|
|
```
|
|
|
|
**Quick output snapshot:**
|
|
```bash
|
|
tmux capture-pane -t task-build-1729519263 -p
|
|
```
|
|
|
|
**Poll output without attaching:**
|
|
```bash
|
|
./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>`
|