name: rch description: >- Offload cargo/gcc/bun builds to remote workers. Use when compilation is slow, workers are unhealthy, hook routing is unclear, or remote sync/execution is failing.
RCH — Remote Compilation Helper
Use this skill for remote compilation offload, worker fleet health checks, and hook incident recovery.
Quick Start
rch check
rch status --workers --jobs
rch workers probe --all
rch hook status
rch diagnose --dry-run "cargo check --workspace --all-targets"
rch exec -- env CARGO_TARGET_DIR=${TMPDIR:-/tmp}/rch_target_<name> cargo check --workspace --all-targets
IMPORTANT: Always use ${TMPDIR:-/tmp} for target dirs, never hardcode /tmp or /var/tmp. On fleet machines TMPDIR=/data/tmp (disk-backed). Hardcoding /tmp wastes tmpfs RAM; /var/tmp survives reboots and accumulates silently.
If rch exec -- ... succeeds, remote offload is healthy and remaining failures are likely project/toolchain specific.
If rch status shows storage pressure, always check both / and /tmp on the worker before deciding what to fix:
ssh ubuntu@<host> 'df -h / /tmp && free -h && cat /proc/pressure/memory && cat /proc/pressure/io'
Fast Triage Order
Run in this order and stop at the first failing stage:
- Availability
rch check
rch status --workers --jobs
rch workers probe --all
rch queue
- Config + socket consistency
rch config show --sources
rch --json config get general.socket_path
rch --json daemon status
- Hook integration
rch hook status
rch agents status
rch hook install
- Command classification + path closure
rch diagnose "cargo build --release"
rch diagnose --dry-run "cargo test --workspace"
- Remote compile proof
rch exec -- env CARGO_TARGET_DIR=${TMPDIR:-/tmp}/rch_target_<name> cargo check --workspace --all-targets
- If sync fails or storage looks bad, inspect the worker directly
ssh ubuntu@<host> 'df -h / /tmp'
ssh ubuntu@<host> 'du -sh /tmp/rch-* /tmp/rch_target_* 2>/dev/null | sort -h'
ssh ubuntu@<host> 'find /data/projects -maxdepth 2 -type d \\( -name "target_rch_*" -o -name "target_*" -o -name "target-*" -o -name target \\) -exec du -sh {} + 2>/dev/null | sort -h | tail'
Quick Fixes
| Symptom | Command |
|---|---|
| Hook not installed | rch hook install && rch hook status |
| Daemon not running | rch daemon start |
| Socket mismatch / stale daemon state | rch daemon restart -y then rch --json daemon status |
| No workers configured | rch workers discover --add --yes && rch workers setup --all |
| Workers unreachable | rch workers probe --all then fix SSH key/host reachability |
| Transfer churn under target dirs | Add excludes in ~/.config/rch/config.toml, then rch daemon reload |
| Path dependency missing remotely | Ensure required sibling repos exist on workers under canonical project roots, then retry rch exec -- ... |
Sync fails with Permission denied in /data/projects/<repo> | Fix remote mirror ownership: ssh ubuntu@<host> 'sudo chown -R ubuntu:ubuntu /data/projects/<repo> && sudo chmod 775 /data/projects/<repo>' |
| Worker shows pressure warning | Check / and /tmp separately, then inspect stale rch_target_*, rch-*, and target_rch_* dirs before broader cleanup |
| Need full environment diagnosis | rch doctor and rch config doctor |
Reference Index
Use these files for full depth:
- Runbooks + operational playbooks:
references/OPERATIONS.md - Troubleshooting flow + failure signatures:
references/TROUBLESHOOTING.md - Worker lifecycle operations:
references/WORKERS.md - Config hierarchy + environment controls:
references/CONFIGURATION.md - PreToolUse hook protocol and behavior:
references/HOOKS.md - Workers config template:
assets/workers-template.toml - Project docs: https://github.com/Dicklesworthstone/remote_compilation_helper