mguozhen/paperclip-remote-agent-skill

Última atividade de origem registrada: 11 de abril de 2026 às 21:12

Catálogo do SkillsMP atualizado: 2 de novembro de 2026 às 18:02

skills coletadas: 1

Estrelas no GitHub: 1
Forks no GitHub: 0

Instalar com um assistente de IA

Copie este prompt para o assistente de IA que você usa.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/mguozhen/paperclip-remote-agent-skill.

README do repositório

Arquivo de origem do README: README.md

Ler o README original

Expandir README completo

# paperclip-remote-agent-skill A Claude Code skill that turns any machine into a remote Paperclip agent host. The skill installs an HTTP listener, exposes it through a Cloudflare Quick Tunnel, and registers the machine with the Paperclip control plane. ## What it does When invoked, the skill performs a one-shot, fully automated setup: 1. Preflight checks (Node.js, Claude Code, cloudflared) 2. Creates `~/paperclip-remote/` workspace 3. Drops a small Node.js HTTP listener at `~/paperclip-remote/listener.mjs` 4. Starts the listener (port 7700) 5. Starts a Cloudflare Quick Tunnel (`*.trycloudflare.com`) pointing at :7700 6. PATCHes the Paperclip server with the new tunnel URL and adapter config 7. Installs launchd plists so listener + tunnel survive reboots 8. Writes a heartbeat SOP to `~/paperclip-remote/CLAUDE.md` so remote Claude follows the checkout → execute → report flow on every wake 9. Verifies end-to-end ## Known tradeoffs Quick Tunnels (`https://*.trycloudflare.com`) are zero-login and zero-setup, which is the whole reason we use them. The tradeoffs you inherit: - The public URL **rotates** on every cloudflared restart. The skill always re-registers on run, so as long as you re-run the skill after any tunnel restart things recover automatically. - A single HTTP request is **capped at ~100s** at the Cloudflare edge. Heartbeats that need to do real work longer than that will return HTTP 524. If either of those is a dealbreaker for your workload, migrate to a named tunnel (this skill does not do that for you). ## Layout ``` . ├── SKILL.md # the skill itself (Claude Code reads this) ├── tests/ │ └── test_skill.sh # 17 unit + regression tests, no external deps └── README.md ``` ## Installing into Claude Code Drop this directory into your `~/.claude/skills/` directory (or symlink it): ```bash ln -s "$PWD" ~/.claude/skills/paperclip-remote-agent ``` Then in any Claude Code session say something like **"setup paperclip remote agent"** and the skill will trigger. ## Running the tests ```bash bash tests/test_skill.sh ``` The suite extracts `listener.mjs` from `SKILL.md`, runs it on port `17700`, and exercises the HTTP contract end-to-end. No mocks. ``` RESULTS: 17 passed, 0 failed ``` ### What's covered | ID | Type | Coverage | |-----|------------|----------| | T0 | sanity | `SKILL.md` exists and is non-empty | | T1 | extract | `listener.mjs` extractable from a fenced `js` block | | T2 | static | `node --check` passes | | T3 | runtime | listener boots, `/health` returns `{status:"ok"}` | | T4 | contract | `/execute /bin/echo` → stdout captured, exit 0 | | T5 | contract | `prompt` field arrives on child stdin verbatim | | T6 | contract | non-zero exit code propagated | | T7 | contract | `timeoutSec:1` SIGTERMs `sleep 10` | | T8 | contract | `activeRuns` counter 0 → 1 → 0 | | T9 | contract | unknown route → 404 | | **R1** | **regression** | **payload `env.PAPERCLIP_API_URL` overrides the listener-startup `LOCAL_API_URL`** | | R2 | regression | arbitrary env (`PAPERCLIP_TASK_ID`, `PAPERCLIP_RUN_ID`) reaches child | | R3 | regression | payload `cwd` honoured | | T10 | static | every `bash` fenced block in `SKILL.md` passes `bash -n` | | T11 | static | skill actually runs `cloudflared tunnel --url http://localhost:7700` | | T12 | static | skill parses a `trycloudflare.com` URL from the tunnel log | | T13 | static | Layer-1 HOME bug is documented in the troubleshooting table | R1 is the load-bearing one. It catches the bug where the listener locked `PAPERCLIP_API_URL` to its own startup environment and silently clobbered the value sent in each `/execute` payload. That bug caused remote claude to silently exit 0 with zero output for ~24h before being root-caused. ## Prerequisites on the target machine - Node.js 18+ - Claude Code (`@anthropic-ai/claude-code`) installed and logged in - `cloudflared` installed (no Cloudflare account login required — quick tunnels work anonymously) - Your Paperclip control plane reachable (default: `https://paperclip.solveaagent.com`) ## Upstream compatibility This skill is a **community plugin** for [`paperclipai/paperclip`](https://github.com/paperclipai/paperclip). It is not (yet) part of the upstream repo. It assumes the Paperclip server supports a `claude_remote` adapter type — i.e. an adapter that POSTs `{runId, prompt, command, args, env, cwd, timeoutSec}` to a remote HTTP `/execute` endpoint and parses the returned `{exitCode, signal, stdout, stderr, timedOut}` as a Claude stream-json run. If your Paperclip fork does not already carry that adapter, this skill won't register the agent successfully. See the companion PR proposal for the upstream change set. Tested against Paperclip server at commit ~`2026-04`, Claude Code `2.1.101`, cloudflared `2026.3.x`, macOS `darwin_arm64`. ## License MIT

Carregando o README do repositório…

Skills neste repositório

Desenvolvedores de software

1 categorias ocupacionais · 100% classificado

skill

ocupação

descrição

atualizado

paperclip-remote-agent

Desenvolvedores de software

One-click setup for Paperclip remote agent. Installs listener, starts tunnel, registers with server. Triggers: paperclip remote setup, setup remote agent, remote agent setup, 远程agent配置

Idioma do texto original: inglês

2026-04-11

Mostrando 1 de 1 skills coletadas.