Skip to content
Skills Library
AI & agents · Automation

remote-agents

/remote-agents

Orchestrate headless Claude Code (`claude -p`) and Codex (`codex exec`) workers on a remote Linux SSH host (default `jetson`, override with REMOTO_HOST) from the local session: probe hosts, spawn jobs, wait, collect results, cross-review across providers, report fleet status. Use when work should run on a remote box (its GPU, files, environment) while this session coordinates: 'run this on the jetson', 'spawn remote agents', 'remote swarm', 'status of the remote jobs', 'córrelo en el jetson', 'lanza agentes remotos', 'cómo van los jobs remotos'. Also for checking or collecting jobs spawned ear

Repository
jaiskills ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/remoto.sh

What it does and when to use it

Orchestrate headless Claude Code (`claude -p`) and Codex (`codex exec`) workers on a remote Linux SSH host (default `jetson`, override with REMOTO_HOST) from the local session: probe hosts, spawn jobs, wait, collect results, cross-review across providers, report fleet status. Use when work should run on a remote box (its GPU, files, environment) while this session coordinates: 'run this on the jetson', 'spawn remote agents', 'remote swarm', 'status of the remote jobs', 'córrelo en el jetson', 'lanza agentes remotos', 'cómo van los jobs remotos'. Also for checking or collecting jobs spawned ear

Triggers from the description

run this on the jetsonspawn remote agentsremote swarmstatus of the remote jobscórrelo en el jetsonlanza agentes remotoscómo van los jobs remotos

Arguments

/remote-agents <task> [--host <ssh-host>] [--engine codex|claude|both] [--dir <remote workdir>] | status [job-id ...]
Original author description

Orchestrate headless Claude Code (`claude -p`) and Codex (`codex exec`) workers on a remote Linux SSH host (default `jetson`, override with REMOTO_HOST) from the local session: probe hosts, spawn jobs, wait, collect results, cross-review across providers, report fleet status. Use when work should run on a remote box (its GPU, files, environment) while this session coordinates: 'run this on the jetson', 'spawn remote agents', 'remote swarm', 'status of the remote jobs', 'córrelo en el jetson', 'lanza agentes remotos', 'cómo van los jobs remotos'. Also for checking or collecting jobs spawned ear

How it works

  1. Runner and host
  2. Arguments
  3. Engines and roles
  4. CLI quick reference
  5. Status mode
  6. Orchestration workflow
  7. Rules
Original SKILL.md headings · 96 lines, 1,212 words
SKILL.md preview
---
name: remote-agents
description: "Orchestrate headless Claude Code (`claude -p`) and Codex (`codex exec`) workers on a remote Linux SSH host (default `jetson`, override with REMOTO_HOST) from the local session: probe hosts, spawn jobs, wait, collect results, cross-review across providers, report fleet status. Use when work should run on a remote box (its GPU, files, environment) while this session coordinates: 'run this on the jetson', 'spawn remote agents', 'remote swarm', 'status of the remote jobs', 'córrelo en el jetson', 'lanza agentes remotos', 'cómo van los jobs remotos'. Also for checking or collecting jobs spawned earlier. NOT for local-only work or local subagents, and NOT usable without an SSH host that has key auth and a logged-in claude or codex."
argument-hint: "<task> [--host <ssh-host>] [--engine codex|claude|both] [--dir <remote workdir>] | status [job-id ...]"
---

You are the **orchestrator** in the local session. Workers are headless `claude -p` / `codex exec` processes on a remote SSH host. Never implement remotely yourself: spawn jobs, poll, collect, synthesize.

Request: $ARGUMENTS

## Runner and host

Every mechanic goes through one script in this skill's directory:

```bash
REMOTO="${CLAUDE_SKILL_DIR}/scripts/remoto.sh"   # other harnesses: absolute path of scripts/remoto.sh beside this SKILL.md
```

Host selection (environment; prefix any call, e.g. `REMOTO_HOST=gpu-box $REMOTO ls`):

| Variable | Effect | Default |
|---|---|---|
| `REMOTO_HOST` | Host every command targets | `jetson` (Jairo's Jetson) |
| `REMOTO_FALLBACK_HOST` | Second host `hosts` probes; retarget to it with `REMOTO_HOST=<it>` when the primary is DOWN | `jetson-ts` (Tailscale route) when `REMOTO_HOST` is unset, none otherwise |
| `REMOTO_HOSTS` | Explicit list for `hosts` | `$REMOTO_HOST $REMOTO_FALLBACK_HOST` |

A host is anything `ssh <host>` resolves (ssh config alias, `user@ip`, Tailscale name). The host must be Linux with key-based SSH (BatchMode, no prompts), bash, `setsid`, python3, and `claude` and/or `codex` logged in on PATH. Local side needs only ssh and rsync. Job state lives on the host in `~/.remoto/jobs/<id>/`, so jobs survive disconnects and are visible to every session.

## Arguments

Parse `$ARGUMENTS`; when empty (model-invoked), read the same fields from the user's latest message:

- `status [job-id ...]`, or a question about existing jobs → **Status mode** below. Do not spawn.
- `--host <h>` → prefix every call with `REMOTO_HOST=<h>`.
- `--engine codex|claude|both` → implementer engine (default `codex`). `both`: one implementer per engine on separate clones/worktrees, compare the two REPORTs, pick one, cross-review it with the other engine.
- `--dir <path>` → remote workdir. Quote tildes (`'~/code/x'`) so they expand on the host; the script refuses local-home paths.
- The rest is the task. No task and no status question → ask for the task.

## Engines and roles

Both engines are driven the same way: headless CLI, prompt on stdin, answer as final message, never through an MCP server. Role is orthogonal to engine; only the prompt changes.

| Role | Who | Spawn flags |
|---|---|---|
| Orchestrator | This session. Never delegated. | — |
| Implementer (default) | Codex at high reasoning | `-e codex -r high` |
| Implementer (alt: user asks for Claude, or `--engine claude`) | Claude Code headless | `-e claude` |
| Reviewer | The engine that did NOT write the work | per engine above |
| Judge (final verdict on a review loop) | The engine that did NOT write the work, so the author's provider never grades itself (default Codex implementer → Claude judge) | `-e claude`, or `-e codex -r high` when Claude implemented |

Models: omit `-m` and the host CLI uses its own configured default (`model` in the host's `~/.codex/config.toml`; Claude Code's model setting on the host). That config is the single place the current defaults live; change it there, not in prompts. Pass `-m <name>` only when the user names a model or the task needs a specific one. `hosts` prints each CLI's version.

`-r/--effort low|medium|high|xhigh` maps to Codex `model_reasoning_effort`; it is codex-only (headless claude has no effort flag; the script rejects it).

## CLI quick reference

| Command | Purpose |
|---|---|
| `$REMOTO hosts` | Probe hosts: UP/DOWN, CLI versions, load; first line names the target |
| `$REMOTO spawn -e claude\|codex -d <remote-dir> [-m model] [-r effort] [-n name] [--safe] -` | Launch a worker, prompt on stdin. Prints the job id |
| `$REMOTO ls` / `status <id>...` | Fleet / job state: RUNNING, DONE, FAILED(rc), DEAD, MISSING |
| `$REMOTO wait [-t secs] <id>...` | Block until all finish (poll 15 s, default timeout 7200). Exit 0 all DONE, 1 any failed, 124 timeout |
| `$REMOTO logs [-f] <id>` | Tail stderr + stdout |
| `$REMOTO result <id>` | Final answer (claude: parsed from stream-json; codex: last message) |
| `$REMOTO kill <id>` / `clean` | Kill the process group / delete finished job dirs |
| `$REMOTO push <local> <remote>` / `pull <remote> <local>` | rsync payloads and artifacts (mind trailing slashes) |
| `$REMOTO help` | Usage |

## Status mode

1. `$REMOTO hosts`.
2. Job ids given: `$REMOTO status <ids>`, then `$REMOTO result <id>` for each DONE. No ids: `$REMOTO ls` for the whole fleet.
3. For each FAILED or DEAD job, `$REMOTO logs <id>`.
4. Report: running, finished (with the REPORT status line of each result), failed (with the log tail that explains it).

## Orchestration workflow

1. **Probe.** `$REMOTO hosts`. Primary DOWN → retarget with `REMOTO_HOST=<fallback>`. All DOWN → stop and tell the user which hosts were tried.
2. **Prepare the remote workspace.** Every job needs an existing remote directory: check with `ssh <host> 'ls <dir>'`, clone the repo on the host, or `$REMOTO push`. Parallel workers on the same repo get **separate clones or worktrees**; remote workers cannot coordinate with each other.
3. **Write worker prompts.** Workers have zero context from this conversation; every prompt is self-contained. Read [references/prompt-templates.md](references/prompt-templates.md) before writing the first prompt and build from its engine-specific template. Keep its REPORT contract so results are machine-collectable.
4. **Spawn.** Pipe the prompt on stdin (never inline-quote a multi-line prompt):
   ```bash
   $REMOTO spawn -e codex -r high -d '~/code/project' -n api-worker - <<'PROMPT'
   ...full self-contained prompt...
   PROMPT
   ```
   Spawn independent jobs back to back in one shell call; capture every printed job id.
5. **Wait without blocking the user.** Run `$REMOTO wait <ids>` in the background (Claude Code: Bash with `run_in_background: true`) and keep doing local work. Jobs can take many minutes; spot-check long ones with `logs`.
6. **Collect.** Per job: `status`, then `result <id>`, then read the REPORT block. FAILED or DEAD → read `logs <id>` before deciding to respawn. Never retry silently.
7. **Cross-review (nontrivial work).** Spawn a fresh reviewer on the *other* engine over the worker's uncommitted diff in the same workdir (reviewer template). Findings → fixer job → re-review, max 2 rounds. High-stakes changes: close with a **judge** job (judge template) that scores the review loop instead of re-reviewing the code.
8. **Verify and deliver.** `$REMOTO pull` artifacts if needed, run or inspect what came back, then report: what ran on which host, results, failures, remote paths. `$REMOTO clean` once the user is done with the batch.

## Rules

- **Self-contained prompts.** The top failure mode is a prompt that references context the worker cannot see. Include repo path, task, constraints, verification commands, and the REPORT contract.
- **One job = one task.** Split multiple deliverables into parallel jobs.
- **Permissions.** Default is full bypass (claude `--dangerously-skip-permissions`, codex `--dangerously-bypass-approvals-and-sandbox`): use only on a host you own that holds nothing you cannot lose. Pass `--safe` when the task only edits files (claude `acceptEdits`, codex `--sandbox workspace-write`).
- **Do not kill what you did not spawn.** `ls` shows every job on the host, including other sessions'.
- **Ground the report.** A job succeeded only after DONE status *and* a result whose REPORT says success; DONE with an error-shaped result is a failure.
- **No background remnants.** Headless processes die with their background children. Every worker prompt says: "Do all polling/waiting synchronously; do not leave background tasks running; your final message must contain all evidence." A result that says "waiting for background tasks" is incomplete: verify the work directly or respawn.
Files in this package (4)
  • SKILL.md 9 KB
  • agents/openai.yaml 1 KB
  • references/prompt-templates.md 8 KB
  • scripts/remoto.sh 11 KB

Versions

The database has no other skills named remote-agents.

Database snapshot: 13.11.2026 · package version f6785d44102f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100remote-orchestrator
    Run the local Claude Code session as an orchestrator while a nested worker session on a remote SSH host (cloud VM, dev box, homelab) does the actual processing - cloning, installing, coding, testing, committing and opening PRs. The orchestrator plans, briefs, reviews and merges.…
  • 100crossagent
    Split or run work across this machine and the user's other machines over ssh (the hosts in ~/.config/crossagent/hosts.json). Local work goes to native Claude Code subagents, work on another host to its <host>-worker subagent (a headless Claude Code there that the user can watch…
  • 100grok-spawn
    Spawn headless grok worker fleets via preflight and spawn_grok_batch. Use when the user asks to run work on a fleet or batch of headless grok workers.
  • 100codex
    Use when you need to run OpenAI Codex CLI from another agent (Claude Code or any shell-capable agent): hand it a task with `codex exec`, run several Codex workers in parallel, continue a Codex session with `codex exec resume`, run `codex exec review`, capture its final report,…
  • 100codex-cli
    Use when an agent needs to delegate a task to the OpenAI Codex CLI from another agent environment such as Claude Code, OpenClaw, or similar. Covers checking whether Codex CLI is installed, running one-off Codex prompts with `codex exec`, resuming sessions, collecting outputs,…
  • 100spawn-ours-agent
    Spawn and configure an ours-fleet agent from Claude Code, using a permanent or temporary lifetime and an ACP session. Use when the user says "spawn ours agent", "spawn an agent", "create a fleet agent", "start a background agent", or asks for a separate supervised agent.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.