From terminal-guru
This skill should be used when working with Unix process signals, shell trap handlers, macOS unified logging, file watching, process monitoring, and terminal notifications. Use when users ask to "check system logs", "debug my app", "fix script cleanup on Ctrl+C", "add signal handling to a script", "configure log streaming", "build a file watcher", "send a notification from the terminal", or "open a log stream in tmux".
How this skill is triggered — by the user, by Claude, or both
Slash command
/terminal-guru:signals-monitoringThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Two closely paired terminal primitives: **signals** (sending and handling Unix process signals in shell scripts) and **monitoring** (observing system state via macOS unified logging, file watching, and process inspection). Completes the loop with **notifications** — alert yourself when something happens.
Two closely paired terminal primitives: signals (sending and handling Unix process signals in shell scripts) and monitoring (observing system state via macOS unified logging, file watching, and process inspection). Completes the loop with notifications — alert yourself when something happens.
log show, log stream)logwatch)logger)trapfswatch, entr)osascript, terminal-notifier)Read, stream, and write to macOS's unified logging system. See references/macos_logging_guide.md for the full reference.
Common operations:
# Show logs from last hour, filtered to a subsystem
sudo log show --last 1h --predicate 'subsystem=="com.apple.sharing"'
# Real-time stream — errors from a process
sudo log stream --predicate 'process=="Safari" and type=error'
# Stream filtered by subsystem in shorthand
sudo log stream --predicate 's=com.apple.networking and type=error|fault'
# Write a log entry from a script
logger -t "my-script" -p user.info "task started"
# Find your entries later
log show --last 1h --predicate 'process=="logger" and eventMessage contains "my-script"'
When to use: Diagnosing macOS app or system behavior, instrumenting shell scripts, post-mortem investigation of crashes or unexpected behavior.
Send, catch, and handle process signals in shell scripts. See references/signals_guide.md for the full reference.
Common operations:
# Graceful shutdown
kill -TERM <pid>
# Reload config (nginx, sshd, launchd services)
kill -HUP $(pgrep nginx)
# Force kill (uncatchable)
kill -9 <pid>
pkill -f "process name pattern"
trap for script cleanup:
# Cleanup temp files on any exit
trap 'rm -f /tmp/my-lockfile' EXIT
# Graceful shutdown handler
trap 'echo "interrupted, cleaning up..."; cleanup_fn; exit 1' INT TERM
# Reload config on HUP
trap 'source ~/.zshrc' HUP
When to use: Scripts that create temp files, hold locks, or run background processes — always add an EXIT trap. Long-running functions that should handle Ctrl+C gracefully.
Run commands automatically when files change. See references/file_watching_guide.md for the full reference.
# Run make when any source file changes (requires: brew install fswatch)
fswatch -o ./src | xargs -n1 -I{} make build
# Re-run tests on source changes (requires: brew install entr)
ls src/**/*.swift | entr -c swift test
# Watch and notify on change
fswatch ~/important-file | xargs -n1 -I{} terminal-notifier -message "File changed"
When to use: Development workflows where you want automatic rebuild/test on save, or monitoring a config file for changes.
Send macOS notifications from the terminal. See references/notifications_guide.md for the full reference.
# Native — no dependencies
osascript -e 'display notification "Build done" with title "Terminal" sound name "Glass"'
# terminal-notifier — richer options (brew install terminal-notifier)
terminal-notifier -title "Deploy" -message "Production live" -sound default
notify_when_done pattern — wrap any command and alert on completion:
notify_when_done() {
"$@"
local status=$?
if (( status == 0 )); then
osascript -e "display notification \"$*\" with title \"Done ✓\" sound name \"Glass\""
else
osascript -e "display notification \"$* (exit $status)\" with title \"Failed ✗\" sound name \"Basso\""
fi
return $status
}
# Usage: notify_when_done make build
# Usage: notify_when_done kubectl apply -f deployment.yaml
When to use: Long-running commands (builds, deploys, test suites) where you want to be alerted when done so you can context-switch away.
logwatch — tmux Log Stream PaneOpen a tmux split pane with a filtered real-time log stream. Useful while developing: keep a log stream open alongside your editor or test runner.
# Install the autoload function
bash /path/to/zsh-dev/scripts/install_autoload.sh logwatch
# Usage after install:
logwatch com.apple.sharing # stream by subsystem
logwatch "" "process==\"Safari\"" # stream by raw predicate
logwatch # stream all (unfiltered)
The script is at scripts/logwatch. When inside tmux, it opens a new split pane; otherwise streams in the current terminal.
| Symptom | Domain | Reference |
|---|---|---|
| App misbehaving, crash investigation | macOS Logging | references/macos_logging_guide.md |
| Script not handling Ctrl+C, leaving temp files | Signals / trap | references/signals_guide.md |
| Want to rebuild/test automatically on file save | File Watching | references/file_watching_guide.md |
| Alert when long command finishes | Notifications | references/notifications_guide.md |
| Need to kill or pause a process | Signals | references/signals_guide.md |
sudo log stream --predicate 'process=="AppName"' --level debugand type=error to focus on errorssudo log show --last 30m --predicate 'process=="AppName"'references/macos_logging_guide.md for predicate syntaxtrap 'rm -f "$tmpfile"' EXIT at the top of your scriptreferences/signals_guide.md for trap patternsbrew install entrls src/**/*.swift | entr -c swift testfswatch -o ./src | xargs -n1 -I{} make testreferences/file_watching_guide.mdnotify_when_done kubectl apply -f k8s/make deploy && osascript -e 'display notification "Deploy done" with title "CI"'references/notifications_guide.mdlogwatch — zsh autoload function: open tmux pane with filtered log streammacos_logging_guide.md — macOS unified log command, predicate filtering, writing logs from shellsignals_guide.md — Unix signal table, kill/pkill, trap patterns for shell scriptsfile_watching_guide.md — fswatch, entr, process inspection (pgrep, lsof)notifications_guide.md — osascript notifications, terminal-notifier, notify_when_done patternThe following tools exist for deep system tracing and are known to this skill, but not yet covered in v1 guidance. Ask about them and expect a pointer to documentation rather than step-by-step help:
dtrace / dtruss — DTrace-based system call tracing (requires SIP disabled on modern macOS)instruments CLI — Apple's profiling and tracing tool (xcrun xctrace)ktrace / kdebug — kernel-level event tracingnpx claudepluginhub totallygreg/claude-mp --plugin terminal-guruDiagnoses macOS issues: kernel panics, failing drives, slow boot, TCC permission denials, APFS snapshot bloat, wake failures, launchd audits, and startup item triage via logs, diskutil, and sysdiagnose.
Automates macOS disk cleanup and memory monitoring with Mole-based safety guards and LaunchAgent alerting. Responds to low disk space, kernel panics, and vm-compressor shortages on Apple Silicon.
Analyzes iOS app crash logs from simulators/devices/TestFlight, symbolicates stack traces with dSYM files using atos, identifies common patterns and root causes.