/setup

name: rr:setup
description: Set up rr for a project - creates configs, verifies SSH connectivity, tests remote execution, and ensures dependencies are available on remote hosts.
allowed-tools:
    - Bash
    - Read
    - Edit
    - Write
    - Grep
    - Glob
load-skills:
    - rr

rr Setup

Use the `rr` skill

Set up and verify rr for this project. Work through each step in order, fixing issues as they arise.

Step 1: Global Config

Check if `~/.rr/config.yaml` exists with valid hosts:

cat ~/.rr/config.yaml

If missing or empty, ask the user for their remote machine details and help create the config. Refer to the rr skill for config format.

If the user wants rr to run on this machine too (in rotation with remotes, or as the only host, for example so concurrent agents queue on one lock), add it as a local host:

rr host add --local --name dev

A local host runs in place in the project directory with no SSH or sync. Only one host can be local, and it can't be named `local`. Local hosts don't work on native Windows. Projects with no `hosts:` list in `.rr.yaml` pick it up automatically, so mention that to the user if they have other projects.

Step 2: Project Config

Detect the project's tech stack by checking for `package.json`, `go.mod`, `pyproject.toml`, `Makefile`, `Cargo.toml`, etc.

Create or update `.rr.yaml` with:

• Sync exclusions appropriate for the detected stack
• Useful tasks based on the tooling (test, build, lint, etc.)

Refer to the rr skill for config format and task syntax.

Step 3: Verify SSH

Skip the SSH debugging below for a local host: it has no SSH, `rr doctor` skips the SSH key and agent checks when every host is local, and `rr setup <local host>` fails by design.

Run diagnostics:

rr doctor

If SSH fails, debug systematically:

1. Test manual SSH: `ssh <host-alias>` 2. Check SSH config: `grep -A5 "<host-alias>" ~/.ssh/config` 3. Common fixes:

• Password prompt: needs key-based auth
• Host not found: add to `~/.ssh/config`
• Timeout: host unreachable, try alternative address
• **"handshake failed" but ssh works**: Key not in agent. Run `ssh-add ~/.ssh/id_rsa`

**Important for passphrase-protected keys:** Ensure your SSH config includes `AddKeysToAgent yes` and `UseKeychain yes` (macOS) so keys are automatically loaded:

Host your-host
    HostName 192.168.x.x
    User youruser
    IdentityFile ~/.ssh/id_rsa
    AddKeysToAgent yes
    UseKeychain yes

This prevents "handshake failed" errors where `ssh` works but rr cannot connect.

Step 4: Test Execution

Verify basic execution works:

rr exec "pwd"

Then test with sync:

rr run "ls -la"

If the remote directory is wrong, check the `dir` setting in global config. A local host has no `dir`: it runs in the project directory, and the sync phase reports `skipped` with `reason: in_place`.

If rr fails with `CONFIG_NOT_FOUND` naming a `.rr.yaml` above the current checkout, you're in a worktree nested inside the main checkout. Commit `.rr.yaml` (or copy it in) so the worktree has its own.

Step 5: Configure and Verify Requirements

rr supports declarative requirements via the `require:` field. Add required tools to `.rr.yaml`:

# .rr.yaml
require:
  - go        # Go projects
  - node      # Node projects
  - python3   # Python projects
  - uv        # Python package manager

Then verify requirements with doctor:

rr doctor --requirements

**If tools are missing**, rr shows which ones and whether they can be auto-installed. Install the ones with built-in installers:

rr provision --check   # Report what's missing
rr provision --yes     # Install without prompts

Manual Installation

For tools without built-in installers, install via SSH:

# uv (Python package manager)
ssh <host-alias> "curl -LsSf https://astral.sh/uv/install.sh | sh"

# bun (JavaScript runtime)
ssh <host-alias> "curl -fsSL https://bun.sh/install | bash"

# Node.js via nvm
ssh <host-alias> "curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash && source ~/.bashrc && nvm install node"

# Go
ssh <host-alias> "curl -LO https://go.dev/dl/go1.22.0.linux-amd64.tar.gz && sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz"

After installing, update the host's `setup_commands` in `~/.rr/config.yaml` to source the new tools:

setup_commands:
    - source ~/.local/bin/env # uv
    - export PATH="$HOME/.bun/bin:$PATH" # bun
    - export PATH="$HOME/.local/bin:$PATH"

**If setup_commands reference missing files** (e.g., `source ~/.local/bin/env` fails):

1. Install the tool that creates that file (e.g., uv creates `~/.local/bin/env`) 2. Or remove/fix the setup_command in `~/.rr/config.yaml`

Step 6: Final Verification

Run a real command to confirm everything works end-to-end:

rr test  # if task defined
# or
rr run "make test"  # or appropriate command for the project

Troubleshooting Reference

| Problem | Fix | | ------------------- | ----------------------------------------------------------- | | SSH fails | Check `ssh <alias>` manually, verify `~/.ssh/config` | | "handshake failed" | Key not in agent: `ssh-add`, add `AddKeysToAgent yes` to SSH config | | "command not found" | Add `shell: "zsh -l -c"` or `setup_commands` to host config | | Sync slow | Add large dirs to `sync.exclude` | | Lock stuck | `rr unlock` | | Wrong directory | Check `dir` in global config |

LLM Workflow (Machine Interface)

rr emits structured JSON by default (`doctor`, `status`, and `tasks` print a `{"success":...,"data":...}` envelope on stdout), so no extra flags are needed.

Step 1: Check Global Config

cat ~/.rr/config.yaml 2>/dev/null