Teaches Claude to use the rr CLI for syncing code and running commands on remote machines

version
1.5.0
GitHub stars
209

Install

/plugin install rr@rr

Run it inside Claude Code after adding the marketplace with /plugin marketplace add rileyhilliard/rr.

Contents

Discovered from source

Skills 1

rr (Road Runner) CLI

rr syncs code to remote machines and runs commands there. Handles host failover, file sync with rsync, distributed locking, and test output parsing.

Quick Reference

rr run "make test"     # Sync files + run command
rr exec "git status"   # Run command without syncing
rr sync                # Just sync files
rr <taskname>          # Run named task from config
rr tasks               # List tasks
rr setup               # Set up rr in this project: writes .rr.yaml, prints next steps + guide
rr provision           # Install missing tools on hosts
rr doctor              # Diagnose issues
rr unlock <host>       # Release a stuck lock
rr monitor --once --json  # One-shot host metrics snapshot

Two-Config System

rr uses two config files:

ConfigLocationPurpose
Global~/.rr/config.yamlPersonal host definitions (SSH, directories)
Project.rr.yamlShareable project settings (tasks, sync rules)

See config.md for complete config reference.

Minimal Global Config

version: 1
hosts:
  mini:
    ssh: [mac-mini.local, mac-mini-tailscale]
    dir: ${HOME}/projects/${PROJECT}

Minimal Project Config

version: 1
hosts: [mini]

tasks:
  test:
    run: pytest -v

rr ships default sync excludes (.git, .venv, node_modules, caches, agent dirs like .claude/) and applies .gitignore. A custom sync.exclude list replaces the defaults, so copy them in if you set one.

Commands Overview

CommandPurpose
rr run "cmd"Sync files, then run command
rr exec "cmd"Run command without syncing
rr syncJust sync files
rr pull <pattern>Download files from the remote
rr <taskname>Run named task
rr tasksList available tasks
rr statusHost connectivity and which remote dir this tree syncs to
rr provisionInstall missing tools on hosts
rr doctorDiagnose issues
rr unlock [host] / rr unlock --allRelease stuck locks
rr pruneRemove remote dirs left by deleted git worktrees
rr host list/add/removeManage hosts
rr setupSet up rr in the current project
rr setup <host>Set up SSH keys for one host

See commands.md for full command reference.

Common Flags

  • --host <name> - Target specific host
  • --tag <tag> - Select host by tag
  • --local - Run on this machine: through the local: true host (its lock, setup and require) if there is one, otherwise directly in your terminal
  • --cwd <dir> - (run/exec) Directory to run in, relative to the project root
  • --tail N - (run/exec/single-command tasks) Reprint the last N log lines after the result
  • --skip-requirements - (run/exec only) Skip requirement checks
  • --tty - Gives the command a terminal for a person typing at it (sudo prompts). Don't use it as an agent: without a terminal it fails with CONFIG_INVALID, and a command that would prompt needs the user to run it themselves
  • --no-phases - Suppress intermediate phase events; the final result event is still emitted
  • --pretty / -p - Human-readable output (spinners, colors). Default is structured JSON.

Run rr --help or rr <command> --help for complete flag reference.

Tasks

Define reusable commands in .rr.yaml:

tasks:
  test:
    description: Run tests
    run: pytest -v

  deploy:
    steps:
      - name: Build
        run: make build
      - name: Deploy
        run: ./deploy.sh

Run with: rr test, rr deploy

Named tasks always run from the project root, regardless of which subdirectory you invoke them from.

See tasks.md for parallel tasks, multi-step tasks, and dependencies.

Passing Arguments to Tasks

Tasks come in three types. The type determines whether extra args work:

TypeConfig fieldAccepts args?Example
Single-commandrun:Yesrr test tests/test_api.py
Multi-stepsteps:No (errors)rr deploy
Parallelparallel:Only with forward_args: truerr test-all

Rules for single-command tasks:

  • Flag-like args need --. rr parses flags before the task sees them, so rr test -k foo fails with "rr parses flags before the task sees them". Use rr test -- -k foo. Positional args (rr test tests/foo.py) work without it.
  • Args are shell-quoted. rr test -- -k "foo or bar" arrives as one argument. Remote globs and $VARS in args are not expanded; put those in the task's run string.
  • Args are appended to the end of the command, unless the command has an {args} placeholder. {args:-default} supplies a default when no args are given; {{args}} is a literal {args}.
  • Compound commands need a placeholder. If run contains pipes, &&, ;, redirections, $(), or backticks, passing args without an {args} placeholder is an error (otherwise the args would land on the last command in the pipeline).
tasks:
  test:
    run: pytest {args:-tests/} -n 4 | tail -20   # rr test -- -k bond  =>  pytest -k bond -n 4 | tail -20

Parallel tasks reject args, flags included, unless forward_args: true is set (CONFIG_INVALID, with a hint to set it and use --). With it, args are forwarded to every subtask (appended, or substituted into each subtask's {args}). Subtasks that are compound commands need an {args} placeholder, and multi-step subtasks can't take forwarded args. A forwarded test filter can leave some subtasks with zero matching tests (pytest exits 5).

tasks:
  test-backend:
    parallel: [test-backend-api, test-backend-services]
    forward_args: true   # rr test-backend -- -k bond

When a parallel task doesn't forward args, bypass it:

rr run --cwd backend "uv run pytest tests/bond/ -v"

To check a task's type, subtasks, and flags: rr <task> --help. This is faster than reading .rr.yaml.

Choosing the Right Command

Need to run something remotely?
├── Named task exists? → rr <task>
│   ├── Single-command task → rr <task> -- <args>
│   ├── Parallel task (forward_args: true) → rr <task> -- <args>
│   └── Parallel task (default) → rr run --cwd <dir> "<cmd> <args>"
├── No task, files may have changed → rr run "<command>"   (syncs first)
└── Files already synced → rr exec "<command>"   (faster, skips sync)

Quote the whole command: rr run "make test". rr rejects rr run <host> make test and rr run <task> -k foo with an error that shows the correct form (rr run --host <host> "..." or rr <task> -- ...).

Never nest rr inside rr exec. rr may not be installed on the remote:

# Wrong:  rr exec "rr sync && pytest"
# Right:  rr run "pytest"

Where Commands Run

  • rr run/rr exec run in the remote equivalent of your current subdirectory. From backend/, rr run "make" uses backend/Makefile. Use --cwd . to run at the project root, or --cwd <dir> for another subdirectory. details.remote_cwd reports the subdirectory used.
  • Absolute local paths under the project are rewritten to the remote project dir (details.path_rewrites counts them). Absolute paths outside the project draw a warning. Disable with rewrite_paths: false.
  • In a linked git worktree, ${PROJECT} expands to <repo>@<worktree>, so each worktree gets its own remote copy (and its own node_modules/.venv, which means a cold first sync).

Reading rr Output

Output is structured by default. No flags needed.

  • stderr: JSON phase events, one per line (connect, lock, sync, exec), then a final {"type":"result",...} line. Config warnings (unknown keys, removed settings) come first as config events with status: warn; fix what they name.
  • stdout/stderr: the command's own output, passed through raw.
  • Exit code: the remote command's exit code. If rr itself fails before the command runs (config, SSH, lock, sync, missing tools), it exits 1 and writes a JSON error envelope ({"success":false,"error":{"code":...,"message":...,"suggestion":...}}) to stderr instead of a result event. Stopped with Ctrl+C or SIGTERM while waiting for a lock, it exits 130 with INTERRUPTED; nothing ran, so don't retry on your own. rr doctor exits 1 when a check fails.
  • Where it ran: the connect event's host and details.reason. local_flag (--local) and local_mode are deliberate local runs; a warn with hosts_unreachable or all_hosts_locked is a fallback. With a local: true host configured, those runs report its name (e.g. dev) as host, not local, so branch on details.reason, never on host == "local". Older rr binaries report --local as hosts_unreachable; treat that as local_flag.
  • Waiting on a lock: a lock waiting event (one host) or connect waiting event (several hosts) names the holder in details.holders as soon as rr starts waiting.
  • Error codes: branch on error.code. Missing required tools is DEPENDENCY_MISSING (older rr: COMMAND_FAILED with a message starting Missing required tools, so accept both); a mistyped host is HOST_NOT_FOUND; no .rr.yaml is CONFIG_NOT_FOUND, including in a worktree nested in the main checkout that lacks its own .rr.yaml (the message names the outer file rr skipped; copy or commit it in).
{"type":"result","status":"failed","exit_code":1,"host":"mini","duration_s":14.2,"details":{"exec_duration_s":11.8,"log_file":"/home/me/.rr/logs/test-20260101-120000/output.log","summary":{"passed":41,"failed":1,"skipped":0,"errors":0},"failures":[{"name":"test_login","file":"tests/test_auth.py:42","message":"AssertionError: ..."}]}}

Useful details keys on the result event:

KeyMeaning
summaryTest counts (pytest, jest/vitest, go test only)
failuresFailed tests with name, file (file:line), message
no_testsThe runner reported collecting zero tests. Exit code may still be 0.
piped_exit_codeZero tests plus a pipe: the exit code is the last pipeline stage's, not the runner's
log_fileFull raw output (~/.rr/logs/...). Read it instead of rerunning.
hintExplanation of a likely local-vs-remote path mistake
fallbackRan locally because no host was reachable or all were locked (reason; plus wait time and lock holders when locked)
path_rewritesNumber of local paths rewritten to remote paths
remote_cwdSubdirectory the command ran in

Parallel tasks print nothing on stdout by default (only with --stream or --verbose). The result event has total, passed, failed, log_dir, and failures (per subtask: task, host, exit_code, log_file, parsed test failures or an output_tail). Use --stream to see live output prefixed with [host:task].

rr test 2>/dev/null          # stdout only: drops phase events, the result event, AND the command's own stderr
rr test --no-phases          # drops phase events only; command stderr and the final result event still go to stderr
rr test --tail 50            # reprint the last 50 log lines after the result

See machine-interface.md for the event schema and error codes.

Pitfalls

  • Pipes hide failures. Without pipefail, pytest | tail exits with tail's status. Set shell: "bash -o pipefail -c" on the host, or check details.summary/failures.
  • Zero tests isn't success. Check details.no_tests after narrowing with -k, -run, or paths.
  • Locks are per host, shared across projects. A run from another project on the same host blocks you. With several hosts, rr tries the next free one. If all are locked it waits up to lock.wait_timeout (1m) for one to free up, then fails, or runs locally when local_fallback: always (never while a local: true host is locked). With one host it waits up to lock.timeout (5m).
  • rr unlock with no host only works when one host is configured. With several, the host picker only appears in --pretty mode; otherwise pass a name (rr unlock mini) or --all.
  • A local: true host runs in your checkout. It's a host in rotation (locked, selected in order), but it doesn't sync: the run sees your working tree as it is, and its output files land there. --local, local mode and fallback runs go through it too, with its lock, setup and require checks. Projects with no hosts: list include it automatically. If rr is killed, the job it started keeps the lock until it exits.
  • Parallel subtasks on the same host share one remote directory. Have each write reports to its own path (reports/unit.xml, not reports/junit.xml for all). Pulled files land locally in <dest>/<subtask>_<index>/, named like the subtask's log file (test:unit first in the list lands in test-unit_0/).
  • Custom sync.exclude replaces the defaults. Include .git, node_modules, .venv yourself.
  • Relative paths follow your cwd for run/exec (see Where Commands Run). If a path fails, read details.hint.

Remote Environment Bootstrap

Declare required tools with require:. rr checks they exist before syncing and fails with "Missing required tools: ..." (DEPENDENCY_MISSING) if not:

# .rr.yaml
require: [go, node]

tasks:
  build:
    run: make build
    require: [cargo]  # Task-specific requirement
# ~/.rr/config.yaml
hosts:
  gpu-box:
    ssh: [gpu.local]
    require: [nvidia-smi, python3]  # Host-specific requirements

rr provision installs missing tools that have built-in installers (40+). rr run/exec --skip-requirements skips the check.

See requirements.md for complete requirements reference.

Parallel Tasks and Dependencies

tasks:
  test-all:
    setup: pip install -r requirements.txt   # Runs once per host before subtasks
    parallel: [test-unit, test-integration, test-e2e]
    fail_fast: false

  ci:
    depends:
      - parallel: [lint, typecheck]  # Run simultaneously
      - test                         # Then this

Subtask pull: runs after all subtasks finish, pass or fail, into <dest>/<subtask>_<index>/. A failed pull doesn't change the exit code. Subtasks get the same env and setup as single tasks: host env, then defaults.env, then task env; host setup_commands and defaults.setup run after cd into the project dir.

Parallel task flags: --stream, --verbose, --quiet, --fail-fast, --max-parallel N, --no-logs, --dry-run, --local, --host, --tag. --dry-run shows the flattened subtask list and commands.

Dependency flags (tasks with depends): --skip-deps runs only the target task, --from <task> starts partway through the chain.

--repeat N on rr run or a single-command task runs it N times in parallel across hosts for flake detection.

See tasks.md for details.

How It Works

  1. Host selection: Tries hosts in order; for each host, races its SSH aliases (earlier aliases preferred). A local: true host is this machine and needs no SSH. --local skips this and needs no hosts configured; it uses the local host when there is one
  2. Locking: Takes a lock on the host; if it's locked, tries the next host
  3. Requirements: Verifies required tools exist (if configured)
  4. File sync: rsync with exclude/preserve patterns (skipped for a local: true host, which runs in the project dir)
  5. Execution: Runs the command with configured env and setup commands, then releases the lock

Troubleshooting

ProblemFix
SSH failsCheck ssh <alias> manually, verify ~/.ssh/config
SSH_AUTH_FAILED but ssh worksKey not in agent: ssh-add ~/.ssh/id_ed25519, add AddKeysToAgent yes to SSH config
SSH_HOST_KEYHost not in ~/.ssh/known_hosts yet: ssh -o StrictHostKeyChecking=accept-new <alias> exit
"command not found"Add setup_commands or shell: "zsh -l -c" to the host; check require
Sync slowAdd large dirs to sync.exclude
LOCK_HELD / lock timeoutWait, or rr unlock <host> / rr unlock --all if the holder is gone
Unknown task flag errorPut task args after --

See troubleshooting.md for detailed diagnostics.

Setting Up a Project

When asked to set up rr (or a project has no .rr.yaml, or hosts are missing), run rr setup from the project root and follow what it returns. It writes a .rr.yaml with require: and tasks: for the detected stack when there isn't one (an existing file is left alone), and returns data.next_steps in order plus data.guide, the how-to and failure fixes for each step. Hosts need details only the user has, so it never adds them: ask the user, then rr host add. Run rr setup again to see what's left.

Reference Files

Sponsors

Details

Marketplace
rileyhilliard/rr
Source
plugins/rr/
Author
Riley Hilliard
Category
Tools
License
MIT
Keywords
remote, ssh, sync, rsync, development, cli