{"id":42629100,"url":"https://github.com/dicklesworthstone/remote_compilation_helper","last_synced_at":"2026-04-02T11:37:27.089Z","repository":{"id":332919686,"uuid":"1135510028","full_name":"Dicklesworthstone/remote_compilation_helper","owner":"Dicklesworthstone","description":"Intercepts cargo/gcc builds from AI coding agents via hooks and transparently routes them to remote worker machines, returning artifacts as if compiled locally","archived":false,"fork":false,"pushed_at":"2026-02-22T04:36:13.000Z","size":103681,"stargazers_count":29,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-22T09:52:13.987Z","etag":null,"topics":["ai-agents","compilation","developer-tools","distributed-computing","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dicklesworthstone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-16T07:42:34.000Z","updated_at":"2026-02-22T04:36:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Dicklesworthstone/remote_compilation_helper","commit_stats":null,"previous_names":["dicklesworthstone/remote_compilation_helper"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/Dicklesworthstone/remote_compilation_helper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fremote_compilation_helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fremote_compilation_helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fremote_compilation_helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fremote_compilation_helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dicklesworthstone","download_url":"https://codeload.github.com/Dicklesworthstone/remote_compilation_helper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fremote_compilation_helper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30064797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","compilation","developer-tools","distributed-computing","rust"],"created_at":"2026-01-29T05:12:30.095Z","updated_at":"2026-04-02T11:37:27.083Z","avatar_url":"https://github.com/Dicklesworthstone.png","language":"Rust","readme":"# rch — Remote Compilation Helper\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"rch_illustration.webp\" alt=\"rch - Remote Compilation Helper for AI coding agents\"\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003ch3\u003eQuick Install\u003c/h3\u003e\n\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/remote_compilation_helper/main/install.sh?$(date +%s)\" | bash -s -- --easy-mode\n```\n\n\u003cp\u003e\u003cem\u003eInstalls `rch` + `rchd`, bootstraps config, and can install/start the background daemon. If remote execution cannot proceed, RCH fails open to local execution.\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"rch_diagram.webp\" alt=\"rch architecture diagram\"\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n**Transparent remote compilation for multi-agent development**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Rust](https://img.shields.io/badge/rust-nightly%202024-orange.svg)](https://www.rust-lang.org/)\n[![codecov](https://codecov.io/gh/Dicklesworthstone/remote_compilation_helper/graph/badge.svg)](https://codecov.io/gh/Dicklesworthstone/remote_compilation_helper)\n\n\u003c/div\u003e\n\n---\n\n## TL;DR\n\n**Problem**: Many concurrent AI agents can saturate local CPU and make your workstation unusable.\n\n**Solution**: RCH runs as a Claude Code PreToolUse hook, classifies build-like commands in milliseconds, executes them on remote workers, and returns artifacts/output as if they ran locally.\n\n**Design constraint**: RCH is fail-open. If remote execution is not safe/possible, commands run locally.\n\n---\n\n## What RCH Intercepts\n\nRCH currently recognizes and can offload:\n\n| Ecosystem | Intercepted Commands |\n|---|---|\n| Rust | `cargo build`, `cargo check`, `cargo clippy`, `cargo doc`, `cargo test`, `cargo nextest run`, `cargo bench`, `rustc` |\n| Bun/TypeScript | `bun test`, `bun typecheck` |\n| C/C++ | `gcc`, `g++`, `clang`, `clang++` |\n| Build Systems | `make`, `cmake --build`, `ninja`, `meson compile` |\n\nRCH explicitly does **not** intercept local-mutating or interactive patterns (examples):\n\n- Package management: `cargo install`, `cargo clean`, `bun install`, `bun add`, `bun remove`\n- Bun runners/dev: `bun run`, `bun build`, `bun dev`, `bun x` / `bunx`\n- Watch/background/piped/redirected commands where deterministic offload is unsafe\n\n---\n\n## Why It Works Well\n\n- Transparent hook behavior: agents see normal command semantics.\n- 5-tier classification pipeline optimized for very fast non-compilation rejection.\n- Daemon-owned worker state and slot accounting.\n- Cache-aware worker selection and project affinity.\n- Queue + cancellation primitives for overloaded scenarios.\n- Deterministic reliability subsystems for convergence, pressure handling, and remediation.\n- Unified status surface with posture and remediation hints.\n\n---\n\n## Current Architecture\n\n```text\nAgent Shell / Claude Code\n        |\n        v\nPreToolUse Hook -\u003e rch (classifier + hook protocol)\n        |\n        v\n      rchd (daemon)\n      - worker selection\n      - queueing and cancellation metadata\n      - health, alerts, telemetry, history\n      - reliability subsystems (convergence, pressure, triage)\n        |\n        v\nRemote workers (rch-wkr)\n      - execute build/test commands\n      - manage worker cache\n      - report capabilities/health/telemetry\n```\n\nWorkspace crates:\n\n- `rch/`: Hook + primary CLI\n- `rchd/`: Local daemon + scheduling/reliability APIs\n- `rch-wkr/`: Worker execution/caching agent\n- `rch-common/`: Shared protocol/types/patterns/UI foundations\n- `rch-telemetry/`: Telemetry collection/storage integration\n\n---\n\n## Reliability Model (Operational)\n\nRCH now includes a deterministic reliability stack for multi-repo and multi-worker stability:\n\n- **Path-dependency closure planning**: builds can include required repository closure rather than a single root.\n- **Canonical topology enforcement**: worker/project roots are normalized around `/data/projects` and `/dp` conventions.\n- **Repo convergence service**: tracks worker drift vs required repos and can repair drift.\n- **Disk pressure resilience**: pressure scoring, admission control, safe reclaim with active-build protection.\n- **Process triage/remediation**: bounded TERM/KILL escalation with audit trail.\n- **Cancellation orchestration**: deterministic cancellation metadata and worker health integration.\n- **Unified posture/reporting**: status output includes posture, convergence state, pressure, and actionable remediation hints.\n\n---\n\n## Installation\n\n### Recommended: Installer\n\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/remote_compilation_helper/main/install.sh?$(date +%s)\" | bash -s -- --easy-mode\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/Dicklesworthstone/remote_compilation_helper.git\ncd remote_compilation_helper\ncargo build --release\ncp target/release/rch ~/.local/bin/\ncp target/release/rchd ~/.local/bin/\n```\n\n### Source Build Note\n\nThis workspace currently uses FrankenTUI path dependencies (`ftui-*`) from `/dp/frankentui/crates/...` in `Cargo.toml`. Ensure that dependency tree is available when building from source in this environment.\n\n---\n\n## First-Time Setup\n\n### Fastest Path\n\n```bash\nrch init\n```\n\n`rch init` can guide:\n\n1. Worker discovery from SSH config/aliases\n2. Worker probing and selection\n3. `rch-wkr` deployment\n4. Toolchain synchronization\n5. Daemon startup\n6. Hook installation\n7. Validation build\n\n### Manual Path\n\n```bash\n# 1) configure workers\nmkdir -p ~/.config/rch\ncat \u003e ~/.config/rch/workers.toml \u003c\u003c 'TOML'\n[[workers]]\nid = \"css\"\nhost = \"203.0.113.20\"\nuser = \"ubuntu\"\nidentity_file = \"~/.ssh/id_rsa\"\ntotal_slots = 32\npriority = 100\nTOML\n\n# 2) start daemon\nrch daemon start\n\n# 3) verify workers\nrch workers probe --all\n\n# 4) install hook\nrch hook install\n\n# 5) check posture\nrch check\nrch status --workers --jobs\n```\n\n---\n\n## Command Surface\n\nGlobal flags:\n\n```bash\n-v, --verbose\n-q, --quiet\n-j, --json\n-F, --format json|toon\n--color auto|always|never\n```\n\n### Core Operations\n\n```bash\nrch daemon start|stop|restart|status|logs|reload\nrch workers list|capabilities|probe|benchmark|drain|enable|disable\nrch status [--workers] [--jobs]\nrch check\nrch queue [--watch|--follow]\nrch cancel \u003cid\u003e | --all\n```\n\n### Hook + Agent Integration\n\n```bash\nrch hook install|uninstall|status|test\nrch agents list|status|install-hook|uninstall-hook\nrch diagnose \"cargo build --release\"\nrch exec -- cargo build --release\n```\n\n### Config + Diagnostics\n\n```bash\nrch config show|get|set|reset|init|validate|lint|doctor|edit|diff|export\nrch doctor [--fix] [--dry-run]\nrch self-test [--worker \u003cid\u003e|--all]\nrch self-test status\nrch self-test history --limit 10\n```\n\n### Fleet + Release + UX\n\n```bash\nrch update [--check|--rollback|--fleet]\nrch fleet deploy|rollback|status|verify|drain|history\nrch speedscore \u003cworker\u003e|--all [--history]\nrch dashboard   # alias: rch tui\nrch web\nrch schema export|list\nrch completions generate|install|uninstall|status\n```\n\n---\n\n## Configuration\n\nPrimary files:\n\n- User config: `~/.config/rch/config.toml`\n- Worker list: `~/.config/rch/workers.toml`\n- Project override: `.rch/config.toml`\n- Optional project excludes: `.rchignore`\n\nPrecedence (highest first):\n\n1. CLI flags\n2. Environment variables\n3. Profile defaults\n4. `.env` / `.rch.env`\n5. Project config\n6. User config\n7. Built-in defaults\n\n### Minimal Example\n\n```toml\n[general]\nenabled = true\nforce_local = false\nforce_remote = false\nsocket_path = \"~/.cache/rch/rch.sock\"\nlog_level = \"info\"\n\n[compilation]\nconfidence_threshold = 0.85\nmin_local_time_ms = 2000\nremote_speedup_threshold = 1.2\nbuild_slots = 4\ntest_slots = 8\ncheck_slots = 2\nbuild_timeout_sec = 300\ntest_timeout_sec = 1800\nbun_timeout_sec = 600\nexternal_timeout_enabled = true\n\n[transfer]\ncompression_level = 3\nremote_base = \"/tmp/rch\"\nadaptive_compression = true\nverify_artifacts = false\nmax_transfer_mb = 2048\n\n[selection]\nstrategy = \"balanced\"\n\n[self_healing]\nhook_starts_daemon = true\ndaemon_installs_hooks = true\n\n[alerts]\nenabled = true\nsuppress_duplicates_secs = 300\n```\n\nBuilt-in worker selection defaults to `balanced`, which blends speed, load,\nhealth, and cache affinity. Use `priority` only when you want explicit\nworker-priority control, and `fair_fastest` when you want extra load spreading.\n\n### Worker Config Example\n\n```toml\n[[workers]]\nid = \"css\"\nhost = \"203.0.113.20\"\nuser = \"ubuntu\"\nidentity_file = \"~/.ssh/id_rsa\"\ntotal_slots = 32\npriority = 100\ntags = [\"fast\", \"ssd\"]\n```\n\n---\n\n## Output Modes\n\nRCH auto-selects output mode by context:\n\n- `hook`: strict JSON for hook protocol\n- `machine`: explicit machine output (`--json`, `--format`)\n- `interactive`: rich terminal rendering\n- `colored`: ANSI-only when forced without TTY\n- `plain`: text fallback\n\nEnvironment controls:\n\n- `RCH_JSON=1`, `RCH_HOOK_MODE=1`\n- `NO_COLOR=1`, `FORCE_COLOR=1`, `FORCE_COLOR=0`\n- `RCH_OUTPUT_FORMAT=json|toon`, `TOON_DEFAULT_FORMAT`\n\nJSON responses use a stable envelope (`api_version`, `timestamp`, `success`, `data`, `error`).\n\n---\n\n## Monitoring and Observability\n\nRCH exposes observability through daemon APIs and metrics:\n\n- daemon health/readiness endpoints\n- Prometheus metrics collection\n- OpenTelemetry tracing integration\n- telemetry-backed worker SpeedScore history\n- queue/build history, active alerts, cancellation metadata in status APIs\n\nQuick checks:\n\n```bash\nrch status --workers --jobs\nrch speedscore --all\nrch doctor --json\n```\n\n---\n\n## Testing and Validation\n\nWorkspace checks:\n\n```bash\ncargo fmt --check\ncargo check --workspace --all-targets\ncargo clippy --workspace --all-targets -- -D warnings\ncargo test --workspace\n```\n\nReliability and E2E suites are provided under:\n\n- `tests/`\n- `tests/e2e/`\n- `rch-common/tests/` (contract/reliability/perf suites)\n\nIf you are running CPU-intensive validation manually and want explicit offload:\n\n```bash\nrch exec -- cargo check --workspace --all-targets\nrch exec -- cargo test --workspace\nrch exec -- cargo clippy --workspace --all-targets -- -D warnings\n```\n\n---\n\n## Security Model\n\n- Transport uses SSH.\n- Worker commands are constrained to classified execution paths.\n- Sensitive field masking and structured error taxonomy are built in.\n- Sigstore/checksum verification is part of update/release flows.\n- Hook path remains fail-open to avoid deadlocks/stalls.\n\nOperational recommendations:\n\n1. Use workers you control.\n2. Use dedicated SSH keys for worker access.\n3. Keep workers patched and isolated.\n4. Enable telemetry/alerting for production-like use.\n\n---\n\n## Limitations\n\n- Designed around SSH-based Linux worker environments.\n- Tooling assumptions are strongest for Rust and selected build/test commands.\n- Remote performance gains depend on network + worker capacity + project shape.\n- Web dashboard workflows require the `/web` stack and its runtime dependencies.\n\n---\n\n## FAQ\n\n### Does RCH block my command if the daemon/workers fail?\nNo. It fails open and allows local execution.\n\n### Can I force local or force remote per project?\nYes, via `.rch/config.toml` (`general.force_local` / `general.force_remote`).\n\n### Is queue/cancel supported?\nYes. Use `rch queue` and `rch cancel`.\n\n### Can I inspect why a command is or is not intercepted?\nYes. Use `rch diagnose \"\u003ccommand\u003e\"`.\n\n---\n\n## About Contributions\n\nPlease don't take this the wrong way, but I do not accept outside contributions for my projects. You can still open issues and PRs for discussion/proof-of-fix, but I review and re-implement changes independently.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdicklesworthstone%2Fremote_compilation_helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdicklesworthstone%2Fremote_compilation_helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdicklesworthstone%2Fremote_compilation_helper/lists"}