Initial commit

2025-11-30 08:56:13 +08:00
commit 966e739b00
9 changed files with 1805 additions and 0 deletions
--- a/skills/tmux-task-runner/README.md
+++ b/skills/tmux-task-runner/README.md
@@ -0,0 +1,154 @@
+# `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>`