systools

# systools A collection of tools and best practices for common system operations during local development and debugging. ## Port Management ### Check / kill process on a port **Script:** `scripts/portcheck.sh` Use this when a user wants to inspect what's running on a port, get detailed process info, or free up a port. **How to use:** ```bash # Check what's on a port (info only, no killing) bash <skill-path>/scripts/portcheck.sh <port> # Check and kill bash <skill-path>/scripts/portcheck.sh -k <port> bash <skill-path>/scripts/portcheck.sh --kill <port> ``` The script displays a key-value report for each process on the port: - COMMAND, PID, PPID, USER, STAT, %CPU, %MEM, START — from `ps` - TYPE, NAME — from `lsof` (connection type and address) - CWD — the process's working directory With `-k`/`--kill`, the processes are killed after displaying info. **Typical scenarios:** - "What's running on port 3000?" → run without `-k` - "Port 8080 is taken" / "address already in use" → run without `-k` first to show the user, then with `-k` if they confirm - "Kill whatever is on port 5173" → run with `-k` directly ## macOS Health Check ### System health overview **Script:** `scripts/mac-health` **Prerequisites:** macOS only. The script uses `uv run --script` and depends on `psutil`. For CPU temperature, `smctemp` must be installed (`brew tap narugit/tap && brew install smctemp`). A single command that checks CPU temperature, network throughput, CPU load, memory, swap, and disk usage — all with configurable thresholds. Each metric shows a ✅ or ⚠️ status. The script exits with code 1 if any threshold is exceeded. **How to use:** ```bash # Run the health check with default thresholds <skill-path>/scripts/mac-health # Override specific thresholds via -t flags <skill-path>/scripts/mac-health -t cpu_temp_c=60 -t swap_used_gb=0 # Use a custom config file <skill-path>/scripts/mac-health -c /path/to/config.json # Generate a config file with defaults at ~/.config/machealth.json <skill-path>/scripts/mac-health --init-config ``` **What it checks:** | Metric | Key | Default Threshold | |--------|-----|-------------------| | CPU Temperature | `cpu_temp_c` | 80 °C | | Network RX | `net_rx_mbps` | 50 Mbps | | Network TX | `net_tx_mbps` | 50 Mbps | | CPU Load (% of cores) | `cpu_load_pct` | 80% | | Memory Used | `mem_used_pct` | 85% | | Swap Used | `swap_used_gb` | 4 GB | | Disk Used | `disk_used_pct` | 90% | **Typical scenarios:** - "How's my system doing?" / "check my mac health" → run `mac-health` and summarize the output - "Is my CPU overheating?" → run `mac-health` and focus on the CPU Temp line - "My mac feels slow" → run `mac-health` to check CPU load, memory, and swap — high swap or memory pressure often explains perceived slowness - "How much disk space do I have?" → run `mac-health` and highlight the Disk lines (it auto-detects external volumes under /Volumes) - "Swap is too high" → run `mac-health -t swap_used_gb=0` to flag any swap usage ## macOS Memory I/O Analytics ### Monitor memory paging and swap activity **Script:** `scripts/mac-mem-io` **Prerequisites:** macOS only. Uses `uv run --script` with Python ≥3.11 (no third-party deps). Calls `vm_stat`, `sysctl vm.swapusage`, and `memory_pressure` under the hood. This script samples virtual-memory counters at regular intervals and reports real-time I/O rates — page-ins/outs, swap-ins/outs, and compressor activity. It answers the question: "Is my Mac *actively* under memory pressure right now?" as opposed to `mac-health` which gives a point-in-time snapshot of total usage. **How to use:** ```bash # Default: 5 samples at 1-second intervals <skill-path>/scripts/mac-mem-io # Custom: 10 samples at 2-second intervals <skill-path>/scripts/mac-mem-io -i 2 -n 10 ``` **Output columns:** | Column | Meaning | |--------|---------| | `swap_used` | Current swap in use (GB). High alone doesn't mean trouble — can be historical residue. | | `swap_free` | Free swap remaining (GB). | | `mem_free` | System-wide memory free % from `memory_pressure`. | | `pageins` | Rate of VM pages read into memory (MiB/s). Small non-zero values are common. | | `pageouts` | Rate of VM pages written out (MiB/s). Sustained non-zero = pressure. | | `swapins` | Rate of pages read back from swap (MiB/s). Sustained non-zero = swap churn. | | `swapouts` | Rate of pages written to swap (MiB/s). Sustained non-zero = swap churn. | | `compress` | Pages compressed per second. High sustained values = tightening memory. | | `decompress` | Pages decompressed per second. Some activity is normal. | **Exit code:** 0 if no pageouts/swapins/swapouts detected across all samples, 1 if any were observed. This makes it composable in scripts or health checks. **How to interpret results:** - High `swap_used` alone does NOT mean current performance trouble — it may be left over from earlier. - If `pageouts`, `swapins`, and `swapouts` stay near zero, current memory I/O pressure is low regardless of swap_used. - If `pageouts` or swap traffic keep rising every sample and the machine feels slow, memory pressure is real. - Use `mac-health` first for a quick snapshot; reach for `mac-mem-io` when you need to see whether pressure is *active and ongoing*. **Typical scenarios:** - "Is my mac swapping right now?" / "memory pressure?" → run `mac-mem-io` and check if pageouts/swapins/swapouts are non-zero - "My mac feels slow, is it memory?" → run `mac-health` first for overview, then `mac-mem-io` to see if there's active paging - "Watch memory for the next 30 seconds" → run `mac-mem-io -i 2 -n 15` - "Is the compressor working hard?" → run `mac-mem-io` and look at compress/decompress columns - After closing heavy apps: "Did that help?" → run `mac-mem-io -n 3` to confirm pressure dropped ## macOS Dev Resource Cleanup ### Release leaked iOS simulators, agent-browser sessions, and stale cargo artifacts **Script:** `scripts/mac-dev-cleanup` **Prerequisites:** macOS only. Uses `uv run --script` with Python ≥3.11 (no third-party deps). Wraps `ps`, `xcrun simctl`, `agent-browser close`, `osascript`, `memory_pressure`, and for the cargo step `cargo` + [`cargo-sweep`](https://github.com/holmgr/cargo-sweep) (`cargo install cargo-sweep`; the step is skipped if either is missing). The two biggest recurring causes of a degraded `mac-health` reading, and neither cleans up after itself: - **Booted iOS simulators** — each booted device keeps a full `launchd_sim` tree alive: SpringBoard plus dozens of iOS widget extensions at 200–330 MB each. One booted device measured **~196 processes**. - **Leaked `agent-browser` sessions** — the CLI spawns a detached daemon (PPID 1) plus a ~10-process headless Chrome tree that survives the session that created it. Observed running for **days**, with renderers pinned at ~100% CPU each, ~5 of 10 cores gone. Plus one that eats disk instead: **the shared cargo target dir** (`build.target-dir` in `~/.cargo/config.toml`, here `~/Library/Caches/cargo-target`) that every Rust project builds into. It only grows — each dependency version, feature set and toolchain leaves its own artifacts — and reached 24 GB before this step existed. **How to use:** ```bash # See what would be cleaned, change nothing (exit 1 = there is work to do) mac-dev-cleanup --dry-run # Clean everything mac-dev-cleanup # Only one part mac-dev-cleanup --only sim mac-dev-cleanup --only browser mac-dev-cleanup --only cargo # Safe to run mid-session: spare agent-browser sessions younger than 2h mac-dev-cleanup --min-age 2 # One-off deeper cargo cleanup: drop what no build used for a week, cap at 15 GiB mac-dev-cleanup --only cargo --cargo-days 7 --cargo-max-size 15GiB # Behaviour checks (50 assertions, no side effects) mac-dev-cleanup --selftest ``` **What it does:** | Step | Action | |------|--------| | agent-browser | Groups Chrome processes into sessions by `--user-data-dir=…/agent-browser-chrome-<uuid>`, links each to its spawning daemon via the root process's PPID, then `agent-browser close --all`, then SIGTERM→SIGKILL any survivor | | simulators | `xcrun simctl shutdown all`, then quit Simulator.app via AppleScript, falling back to signals when it refuses | | cargo target | Finds the shared target via `cargo metadata` on a throwaway stub project, takes cargo's build locks, then `cargo sweep --time 21` (artifacts no build touched in 21 days) and `cargo sweep --maxsize 20GiB` (least recently used first) | | report | Free-memory % and swap before/after (process steps); target size before/after (cargo step) | **Exit code:** 0 on success. Under `--dry-run`, 1 means there is something to clean — composable as a check like `mac-health`. **Notes / gotchas:** - **The user's own Chrome is never touched.** Session membership is decided solely by the `agent-browser-chrome-<uuid>` user-data-dir; a plain `/Applications/Google Chrome.app/…/Google Chrome` has no such flag. This is covered by explicit safety assertions in `--selftest`. - `ps` truncates the command column to terminal width unless `-ww` is passed, which silently hides processes whose `--user-data-dir` sits past the cutoff — the script always uses `ps -Awwo`. Any ad-hoc `ps | grep` for these processes needs the same flag or it will undercount. - `agent-browser close --all` is all-or-nothing, so `--min-age` switches to selective signalling instead of calling it. - `simctl shutdown all` preserves device data; only running-app state is lost, and devices re-boot on demand. - Simulator.app routinely ignores `quit app "Simulator"`; the signal fallback is the normal path, not an error. - Counting these processes by hand with `ps -A | grep -c <pattern>` self-matches the grep and the parent shell. Use a bracket pattern (`'[s]imruntime'`) or the script's own report. **Cargo step: why it doesn't cause rebuild churn, and its traps:** - "Last used" is the atime of the files in `.fingerprint/<unit>-<hash>/`: cargo reads the hash file there on every build, fresh or not, to decide whether to recompile. So anything a project still builds keeps a fresh atime and survives; only units that no project has touched in N days go. The price is that a project left alone for 3+ weeks rebuilds its dependencies once. - **`cargo sweep --installed` / `--toolchains` poison that signal** — they read every fingerprint `.json` (even with `--dry-run`), stamping the whole target "used today", after which `--time` finds nothing for weeks. The script only uses `--time` / `--maxsize` (stat-only), and before each sweep resets any fingerprint `.json` whose atime is newer than its mtime back to its mtime. Cargo itself reads the `.json` only right before rewriting it, so this loses nothing. Old-toolchain artifacts need no `--installed`: after a `rustup update` nobody uses them, and `--time` collects them. - cargo-sweep takes only a project path and resolves the target via `cargo metadata`; pointing it at the target dir itself fails. The stub project in a temp dir keeps the job independent of any real project. - If a build holds any of `.cargo-lock` / `.cargo-build-lock` / `.cargo-artifact-lock` (all flock(2)), the step skips the run. While sweeping it holds them itself, so a build that starts meanwhile prints `Blocking waiting for file lock on build directory` and waits (both verified against cargo 1.98). - **Size units:** cargo-sweep reads `GB` as 10⁹ and sums apparent file sizes, counting the hardlinks between `incremental/` and `deps/` twice, so its total runs ~5% above `du`. Pass `GiB`. - `~/.cargo/registry` needs none of this: cargo ≥1.88 garbage-collects it on its own. **Scheduled run:** a launchd agent runs the full cleanup **daily at 06:00** (30min after the 5:30AM `pmset repeat wakepoweron`; system sleep is disabled so the machine is reliably awake). Plist lives in the repo at `launchd/com.reorx.mac-dev-cleanup.plist`, symlinked to `~/Library/LaunchAgents/`. Log: `~/Library/Logs/mac-dev-cleanup.log` (each run is stamped — the script prints a timestamp header whenever stdout is not a TTY). ```bash launchctl print gui/$(id -u)/com.reorx.mac-dev-cleanup # status, run count, calendar trigger launchctl kickstart -p gui/$(id -u)/com.reorx.mac-dev-cleanup # force a run now launchctl bootout gui/$(id -u)/com.reorx.mac-dev-cleanup # unload ``` It deliberately has **no `RunAtLoad`** — the job kills browsers and simulators, so it must only fire on schedule, never on login or reload. For the same reason, don't `kickstart` it just to test the cargo step; run `mac-dev-cleanup --only cargo` instead. The plist's `PATH` includes `~/.cargo/bin` for that step; after editing the plist, `bootout` + `bootstrap` it, because launchd reads it only at load. **Typical scenarios:** - "Why is my mac hot / loud / slow?" → run `mac-health`; if load or temp is high, run `mac-dev-cleanup --dry-run` **before** investigating anything else — this has been the top cause - After finishing browser automation or iOS testing → run `mac-dev-cleanup` as the verification teardown step - Periodic hygiene while other sessions may be working → `mac-dev-cleanup --min-age 2` - "The cargo target / Rust cache is huge" → `mac-dev-cleanup --only cargo --dry-run`, then run it; lower `--cargo-days` or `--cargo-max-size` for a one-off deeper cut ## macOS WindowServer Diagnostics ### Find out why WindowServer is hot **Script:** `scripts/window-server-doctor.py` **Prerequisites:** macOS only. Uses `uv run --script` with Python ≥3.11 (no third-party deps). Wraps `ps`, `top`, `lsappinfo`, `system_profiler`, `log show`, `ioreg`, optionally `powermetrics` and `sample` (those two need sudo). When WindowServer is burning CPU, the goal is to find which *other* app is driving its rendering work — so the user can fix it without logging out or quitting apps. This script runs 8 checks and emits a verdict that names likely contributors. **How to use:** ```bash # Fast partial run (no sudo): process stats, foreground apps, displays, log, ioreg <skill-path>/scripts/window-server-doctor.py --quick # Full diagnostic with sudo (enables powermetrics GPU-by-process + sample hot frames) sudo -E <skill-path>/scripts/window-server-doctor.py # Opt in to exact window counts per app (15-25s, needs Automation permission) <skill-path>/scripts/window-server-doctor.py --slow-windows # Machine-readable output <skill-path>/scripts/window-server-doctor.py --json ``` **What it checks:** | # | Check | Needs sudo? | |---|-------|-------------| | 1 | WindowServer PID/CPU/RSS/uptime (`ps`) | No | | 2 | Live thread count + CPU (`top`) | No | | 3 | Foreground apps (`lsappinfo`) — or exact windows/app with `--slow-windows` (System Events) | No | | 4 | Connected displays, resolution, refresh rate (`system_profiler`) | No |