Remote Compilation Helper Setup

RCH Setup

Offloads cargo build, bun test, gcc to remote workers. Transparent—same commands, faster builds.

Workflow

1. rch doctor           # What's broken?
2. rch doctor --fix     # Auto-fix common issues
3. rch doctor           # All green? Done.

If --fix can't solve it, continue below.

Setup Checklist

• [ ] Prerequisites: which rustup rsync zstd (install missing)
• [ ] Install: cargo install --path rch (or --path . from repo root)
• [ ] Configure: Create ~/.config/rch/workers.toml (see below)
• [ ] Hook: rch hook install
• [ ] Daemon: rchd & or systemctl --user start rchd
• [ ] Validate: rch doctor → all checks pass

Worker Config

# ~/.config/rch/workers.toml
[[workers]]
id = "worker1"
host = "192.168.1.100"
user = "ubuntu"
identity_file = "~/.ssh/id_ed25519"
total_slots = 8    # ≈ CPU cores - 2
priority = 100     # Higher = preferred
tags = ["rust"]    # Optional capability tags

Discover from SSH config:

rch workers discover --from-ssh-config --dry-run  # Preview
rch workers discover --from-ssh-config            # Add to config

Verify workers:

rch workers probe worker1 --verbose  # Test single
rch workers probe --all              # Test all
rch workers list --capabilities      # Show detected toolchains

Quick Fixes

Test hook directly:

echo '{"tool":"Bash","input":{"command":"cargo check"}}' | rch hook
# Expect: {"allow":true,"output":"..."}

Validation

rch doctor --verbose   # Full diagnostics
rch doctor --json      # Machine-readable
RCH_DRY_RUN=1 cargo check  # Test without remote execution

⚠️ All `rch doctor` checks must pass before use.

References

Hook Integration

Flow

Claude Code → PreToolUse Hook → rch
                                 │
                    ┌────────────┴────────────┐
                    │ Bash tool?              │
                    │   └─ Compilation cmd?   │
                    │       └─ Yes → Remote   │
                    │       └─ No → Local     │
                    │   └─ No → Pass through  │
                    └─────────────────────────┘

Installation

rch hook install      # Modifies ~/.claude/settings.json
rch hook status       # Verify
rch hook uninstall    # Remove

Adds to settings:

{"hooks":{"PreToolUse":[{"matcher":"Bash","command":"/path/to/rch hook"}]}}

Protocol

Input (stdin):

{"tool":"Bash","input":{"command":"cargo build --release"}}

Output (stdout):

Classification (5-tier, <5ms total)

Intercepted

cargo build/test/check/run, rustc
bun test, bun typecheck
gcc, g++, clang, clang++, cc
make, cmake --build, ninja, meson compile

Never Intercepted

bun install/add/remove     # Modifies node_modules
bun run/dev/build          # Needs local ports
cargo build | tee log      # Piped
cargo build > output.txt   # Redirected
cargo build &              # Background

Testing

# Test classification
echo '{"tool":"Bash","input":{"command":"cargo build"}}' | rch hook
# → {"allow":true,"output":"..."}

echo '{"tool":"Bash","input":{"command":"ls -la"}}' | rch hook
# → {"allow":true}

# Dry run with file input
RCH_DRY_RUN=1 rch hook < test-input.json

# Dry run (logs but no remote execution)
RCH_DRY_RUN=1 cargo check

# Debug logging
RCH_LOG=debug cargo build
RCH_LOG=trace cargo build  # Maximum detail

# Verify hook is running
ps aux | grep rch

Configuration

~/.config/rch/config.toml:

[hook]
classify_timeout_ms = 5      # Classification budget
pipeline_timeout_s = 300     # Full pipeline timeout
fail_open = true             # On error → allow local execution

local_patterns = [           # Force local execution
    "cargo fmt",
    "cargo doc"
]

Uninstalling

rch hook uninstall  # Removes hook from ~/.claude/settings.json

# Manual removal: edit ~/.claude/settings.json and remove the PreToolUse entry

Security

• Runs with user permissions
• SSH keys via ssh-agent (recommended)
• Workers should be trusted machines
• Never modifies source code
• Artifacts transferred via secure rsync

Troubleshooting

First step: rch doctor --verbose

Symptom Index

---

Installation

# Rust nightly not installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup install nightly && rustup default nightly

# Edition 2024 error → need recent nightly
rustup update nightly
rustc +nightly --version  # Need 1.82+

# Missing rsync/zstd
sudo apt install rsync zstd      # Debian/Ubuntu
brew install rsync zstd          # macOS
sudo dnf install rsync zstd      # Fedora

---

SSH Issues

Full SSH debug: ssh -vvv -i ~/.ssh/key user@host "echo ok"

---

Configuration

# No config directory
mkdir -p ~/.config/rch

# Create minimal config
cat > ~/.config/rch/workers.toml << 'EOF'
[[workers]]
id = "worker1"
host = "192.168.1.100"
user = "ubuntu"
identity_file = "~/.ssh/id_ed25519"
total_slots = 8
priority = 100
EOF

# Or use interactive wizard
rch init

# Validate syntax
rch config check

Common TOML mistakes:

• Missing quotes around string values
• [workers] instead of [[workers]]
• Typos in field names

---

Daemon

Daemon logs: journalctl --user -u rchd -f

Deep debug: rchd --foreground --log-level=debug

---

Hook Issues

Commands never intercepted (by design):

• bun install/add/remove (package management)
• bun run/dev/build (local execution)
• Piped: cargo build | tee log
• Background: cargo build &

Test hook directly:

echo '{"tool":"Bash","input":{"command":"cargo build"}}' | rch hook
# Expect: {"allow":true,"output":"..."}

RCH_DRY_RUN=1 cargo check  # Logs decision without remote execution

---

Worker Issues

Install Rust on worker: ssh worker "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh"

Check worker disk: ssh worker "df -h /tmp"

Check rsync compatibility: rsync --version and ssh worker "rsync --version"

---

Performance

Profile transfer: time rsync -avz ./src/ worker:/tmp/test/

Check network: ping -c 5 worker

Debug transfer: RCH_LOG=debug cargo build 2>&1 | grep transfer

---

Debug Mode

export RCH_LOG=debug    # or trace for maximum detail
cargo build             # Logs show hook decisions

# Levels: error, warn, info, debug, trace

---

Getting Help

rch --version              # Show version
rch --help                 # General help
rch doctor --help          # Doctor subcommand help
rch workers --help         # Workers subcommand help

Generate Diagnostic Report

rch doctor --json > diagnostic.json

Worker Configuration

Schema

[[workers]]
id = "unique-name"           # Required
host = "192.168.1.100"       # Required: IP or hostname
user = "ubuntu"              # Required: SSH user
identity_file = "~/.ssh/key" # Required: SSH key path
total_slots = 16             # Required: max concurrent jobs (≈ CPU cores - 2)
priority = 100               # Optional: selection weight (default: 50, higher = preferred)
tags = ["rust", "fast"]      # Optional: capability tags
enabled = true               # Optional: set false to disable (default: true)

Selection Algorithm

score = available_slots × priority × locality_bonus

1. Available slots: total_slots - active_jobs 2. Priority: tiebreaker when slots equal 3. Locality: bonus for workers with cached project data 4. Tags: project can require specific tags via .rch.toml

Multi-Worker Example

# Primary (fast, high priority)
[[workers]]
id = "fast-builder"
host = "build-server.local"
user = "build"
identity_file = "~/.ssh/build_key"
total_slots = 48
priority = 100
tags = ["fast", "rust", "bun"]

# Secondary (fallback when primary busy)
[[workers]]
id = "backup"
host = "192.168.1.50"
user = "ubuntu"
identity_file = "~/.ssh/id_ed25519"
total_slots = 8
priority = 50
tags = ["rust"]

# Specialized TypeScript worker
[[workers]]
id = "ts-builder"
host = "ts.internal"
user = "node"
identity_file = "~/.ssh/ts_key"
total_slots = 16
priority = 75
tags = ["bun", "typescript"]

SSH Config Discovery

rch workers discover --from-ssh-config --dry-run   # Preview
rch workers discover --from-ssh-config             # Add to config
rch workers discover --from-ssh-config --filter "build*"  # Filter by pattern

Required SSH config fields: Host, HostName, User, IdentityFile

Optional RCH hints (in SSH config comments):

Host build-server
    HostName 192.168.1.100
    User ubuntu
    IdentityFile ~/.ssh/build_key
    # rch-slots: 16
    # rch-priority: 90
    # rch-tags: rust,bun

Probing & Monitoring

rch workers probe worker1 --verbose  # Test connectivity + detect toolchains
rch workers probe --all              # Probe all workers
rch workers status                   # Current state
rch workers status --json            # For monitoring tools
watch -n 5 'rch workers status'      # Continuous monitoring

Probe output shows: SSH connectivity, detected toolchains (rustc, cargo, bun, gcc), disk space, load.

Tags

Workers declare capabilities:

[[workers]]
id = "polyglot"
tags = ["rust", "bun", "cpp"]

Projects require tags:

# .rch.toml in project root
required_tags = ["rust", "fast"]

Slot Sizing

ssh worker1 "nproc"  # Check cores
# Rule: total_slots = cores - 2 (leave headroom for system)

Disable/Enable

[[workers]]
id = "under-maintenance"
enabled = false  # Won't be selected