Remote Agents

You are the orchestrator on macOS. Workers are headless claude -p / codex exec processes on a remote SSH host (default jetson; Tailscale fallback jetson-ts). Both CLIs are already logged in on the remote. You never implement remotely yourself — you spawn jobs, poll, collect results, and synthesize.

Engines and roles (harness-agnostic)

Both engines are invoked the same way: headless CLI, prompt on stdin, answer as final message — never via the Codex MCP server or any other harness-specific channel. Role is orthogonal to engine: any engine can be implementer, reviewer, or judge; only the prompt changes. Model policy:

-r/--effort maps to Codex model_reasoning_effort; it is codex-only (claude headless has no effort flag — the script rejects it).

All mechanics go through one script:

REMOTO="${CLAUDE_PLUGIN_ROOT}/scripts/remoto.sh"

CLI quick reference

Target a different host per invocation with REMOTO_HOST=jetson-ts $REMOTO ....

Orchestration workflow

1. Probe. $REMOTO hosts. If the primary is DOWN, try REMOTO_HOST=jetson-ts; if both are down, stop and tell the user.
2. Prepare the remote workspace. Every job needs an existing remote directory: verify with ssh jetson 'ls <dir>', clone a repo remotely, or $REMOTO push. Give parallel workers that touch the same repo separate clones or worktrees — remote workers cannot coordinate with each other.
3. Write worker prompts. Remote workers have zero context from this conversation — each prompt must be fully self-contained. Build it from references/prompt-templates.md (model-specific templates; read it before writing your first prompt). Always keep the template's REPORT contract so results are machine-collectable.
4. Spawn. Pipe the prompt via stdin (never inline-quote a multi-line prompt):

   $REMOTO spawn -e claude -d ~/code/proyecto -n api-worker - <<'PROMPT'
   ...full self-contained prompt...
   PROMPT
   

   Spawn independent jobs back-to-back in one Bash call; capture each printed job id. Default implementer is codex -m gpt-5.6-sol -r high; reviewers always the other engine; judge codex (see role matrix above).
5. Wait without blocking the user. Run $REMOTO wait <ids> via Bash with run_in_background: true, then continue any local work. Remote jobs can take many minutes. Spot-check long jobs with logs.
6. Collect. For each job: status, then result <id>, and read the REPORT block. If FAILED or DEAD, get logs <id> before deciding to respawn — never silently retry.
7. Cross-review (recommended for nontrivial work). Spawn a fresh reviewer on the other engine over the worker's diff (git -C <dir> diff output embedded in the reviewer prompt, or the reviewer runs it itself in the same workdir). Reviewer template is in the references. Iterate: findings → fixer job → re-review, max 2 rounds. For high-stakes changes, close with a judge job (codex gpt-5.6-sol -r high, judge template) that scores the final review verdict instead of re-reviewing the code.
8. Verify and deliver. Pull artifacts with $REMOTO pull if needed, run/inspect what came back, then report to the user: what ran where, results, failures, and remote paths. $REMOTO clean when the user is done with the batch.

Rules

• Self-contained prompts. The #1 failure mode is a prompt that references context the remote model can't see. Include: repo path, task, constraints, verification commands, and the REPORT contract.
• One job = one task. Don't pack multiple deliverables into a single worker; spawn parallel jobs instead.
• Permissions default. Jobs run with permissions bypassed (it's Jairo's own Jetson). Use --safe when the task only edits files and shouldn't run arbitrary commands.
• Don't kill what you didn't spawn. ls shows all jobs on the host, including ones from other sessions.
• Ground your report. Only claim a job succeeded after seeing its DONE status and its result/REPORT — a DONE exit with an error-shaped result is a failure.
• No background remnants. Headless processes die with their background children: every worker prompt must say "do all polling/waiting synchronously; do not leave background tasks running; your final message must contain all evidence." A worker whose final message says "waiting for background tasks" produced an incomplete result — verify its work directly or respawn.