Skip to content
Skills Library
AI & agents · Automation

remote-orchestrator

/remote-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. Use when the user wants work to "run on <host>", "via ssh", "in my remote/VM/OCI/server environment", or "in a nested session", or asks this session to coordinate, review or merge rather than code.

Licence
Apache-2.0
Last repository change
08.11.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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. Use when the user wants work to "run on <host>", "via ssh", "in my remote/VM/OCI/server environment", or "in a nested session", or asks this session to coordinate, review or merge rather than code.

Triggers from the description

run on <host>via sshin my remote/VM/OCI/server environmentin a nested session
Original author description

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. Use when the user wants work to "run on <host>", "via ssh", "in my remote/VM/OCI/server environment", or "in a nested session", or asks this session to coordinate, review or merge rather than code.

How it works

  1. 1. Preflight the host
  2. 2. Settle open decisions before briefing
  3. 3. Start the worker
  4. 4. Write a self-contained brief
  5. 5. Review, merge, iterate
  6. Safety
Original SKILL.md headings · 112 lines, 750 words
SKILL.md preview
---
name: remote-orchestrator
description: 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. Use when the user wants work to "run on <host>", "via ssh", "in my remote/VM/OCI/server environment", or "in a nested session", or asks this session to coordinate, review or merge rather than code.
---

# Remote Orchestrator

There are two roles:

- **Orchestrator** (the local session) settles decisions with the user, writes
  briefs, reviews the worker's PRs, merges, and changes repository settings. It
  doesn't edit project code locally. The local checkout may be stale, and the
  point of this setup is that processing happens on the remote machine.
- **Worker** (a nested session on the SSH host) does all processing in the
  remote checkout, then reports back with links and test results.

The remote box carries the heavy work (dependency installs, builds, test
suites)
and usually matches the CI or production OS. The local session stays light and
keeps the conversation with the user.

Pair this skill with `pr-review-workflow`. The worker follows it as an author,
and the orchestrator follows it as reviewer and merger.

## 1. Preflight the host

From the orchestrator, check the host before starting a worker. A worker that
finds a missing tool halfway through wastes a whole turn.

```bash
ssh -o BatchMode=yes -o ConnectTimeout=10 <host> '
  hostname
  ls -d <project-dir> && git -C <project-dir> status -sb
  command -v git gh <runtime-tools>
  gh auth status'
```

- **Unreachable or prompting for a password:** stop and ask the user. Don't
  work around their SSH config.
- **Project folder missing:** clone it, e.g.
  `ssh <host> 'gh repo clone <owner/name> <project-dir>'`, then check out the
  base branch.
- **`gh` not authenticated or tools missing:** ask the user to fix it on the
  host. Never copy credentials over.

## 2. Settle open decisions before briefing

The worker only sees its brief. Every open question in the brief becomes either
a guess or a stalled session. Ask the user first about anything the repo can't
answer: branch model, scope, who merges, language, naming. Put the answers in
the brief, quoting the user's own words where precision matters.

## 3. Start the worker

**Claude desktop app (Code tab):** start a new session on the saved SSH
connection with the project folder as its working directory. From an agent,
call `start_session` with `target: "ssh"`, `host: "<saved connection name>"`,
`cwd: "<project-dir>"`, a fresh context, and wake-on-done, so the orchestrator
resumes when the worker finishes its turn.

**Claude Code CLI:** run the worker inside tmux on the host so it survives
disconnects:

```bash
scp brief.md <host>:<project-dir>/.brief.md
ssh -t <host> 'tmux new -As worker "cd <project-dir> && claude"'
```

Paste the brief as the first message, or run it headless with
`claude -p "$(cat .brief.md)"`. Keep `.brief.md` out of git.

## 4. Write a self-contained brief

Include:

- **Goal and definition of done.** Name the concrete outputs, e.g. "one issue
  and one PR per item, all CI green".
- **Where:** the host, the project folder, the base branch, and the repo
  (`owner/name`).
- **Decisions already made** and the constraints that follow from them.
- **Workflow:** follow `pr-review-workflow`, and run the repo's own local
  quality gates before every commit.
- **Boundaries:** what the worker must not do (merge, change repository
  settings, push to trunk or release branches, force-push, touch unrelated
  files).
- **Conflict plan:** when it opens several PRs at once, each touches different
  files, or they're stacked.
- **Report format:** issue and PR URLs, what each changes, gate results, and
  open questions. Then end the turn so the orchestrator can review.

## 5. Review, merge, iterate

When the worker reports:

1. Treat the report as a claim, not proof. Read each PR's diff
   (`gh pr diff <n>`) and CI status (`gh pr checks <n>`) yourself.
2. Review against the `pr-review-workflow` checklist. Post the review on the PR
   (`gh pr review <n> --comment -b "..."`), with each point labeled
   `required:` or `nit:`. GitHub doesn't allow approving or requesting changes
   on your own PR, so use a comment when both sessions use the same account.
3. Send required changes back to the **same** worker session, which already has
   the context, rather than starting a new one.
4. Merge only when the merge gate holds:
   `gh pr merge <n> --squash --delete-branch --subject "<PR title>"`.
5. Apply repository settings (rulesets, default branch, merge options) from the
   orchestrator, and only after the checks they reference exist.

## Safety

- Never put secrets in a brief. The worker uses the host's own credentials.
- Keep host names, IPs and private paths out of anything you publish.
- Use one writer per set of files. With several workers, give each its own
  files or its own worktree.
- Repository settings changes, deletions and public posts need the user's
  explicit go-ahead, the same as in a local session.

Versions

The database has no other skills named remote-orchestrator.

Database snapshot: 13.11.2026 · package version 67b041e8435d (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

  • 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…
  • 100remote-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.…
  • 100ao-setup
    First run of Orchestrator Bot: find every computer that runs Orchestrator, save them as AO hosts, add a remote AO host that has no Grok Bot desktop app, and turn on optional routines. On a computer without Orchestrator.inc it helps install it and get it ready: a coding agent, a…
  • 96claude-rc-open
    Start a new Claude Code session in another local repository that can be driven from the phone or claude.ai via Remote Control. It runs as an interactive session with permissions bypassed, in the background, so several can run at once, even in the same repository. Use when the…
  • 100ask
    Ask another agent: message any running Claude Code session or Codex thread, or hand work to a fresh Claude or Codex worker, in any direction (Claude to Claude, Claude to Codex, Codex to Claude, Codex to Codex), on this machine or another over ssh. Use when the user says…
  • 100ssh
    Interact with remote servers via SSH & SFTP tools (mcp__ssh__ssh_exec, mcp__ssh__ssh_system_info, mcp__ssh__ssh_read_file, mcp__ssh__ssh_write_file, mcp__ssh__ssh_list_dir, mcp__ssh__ssh_stat). Use when the user asks to inspect a remote server, run commands on an SSH host, view…

Feedback and reports

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