run-paperclip

run-paperclip

A Claude Code plugin to operate Paperclip companies outside-in from your interactive Claude Code session — acting as the board operator and embodying agents to do real work locally — without triggering a server-side claude -p run (the metered Agent-SDK cost).

New here? Start with the User Guide — a plain-language, founder-facing walkthrough (quick start, the everyday loop, what gets picked up when you work in the UI, every command, and the plain-language asks that cover everything else).

---

What this plugin is

Paperclip is an AI-company control plane. Its agents normally execute server-side via the claude_local adapter, which spawns claude -p. run-paperclip keeps you in control from a real, interactive Claude Code session and relocates the model work onto your subscription by:

1. Operating the board (cheap API calls — bootstrap, hire, assign, monitor, approve). No model runs here.
2. Embodying agents — your interactive session becomes the agent and runs its work loop locally (checkout → load context → do the work → post results → set disposition → release). This is the saving.
3. Cost-safety — agents are configured with a non-executing adapter (external, or process) or with heartbeats disabled, and a guard hook blocks any action that would wake a claude_local agent server-side.

The plugin is skill-first and native-tool-first: it leans on Claude Code's built-in Task*, Agent/Workflow, Monitor, EnterWorktree/EnterPlanMode, and PushNotification rather than custom orchestration code. The sustained hands-off loop (Mode 2.5) is driven by a single persistent Monitor — event-driven, no in-session cron or timer. Custom code is limited to the relay, the guard hooks, the shared helper lib, and the watch script.

The paperclipai CLI is a client of Paperclip's REST API — not a separate interface. The plugin talks to Paperclip CLI-first (paperclipai … --json) and falls back to raw HTTP (curl) only for endpoints the CLI doesn't wrap. There is no bundled MCP.

---

The cost model (read this first)

What costs money is which client runs the model, not whether a human is watching:

Execution style	Who runs the model	Counts against
Server-side claude_local (the default UI path)	Paperclip server, via claude -p	Agent-SDK credit (post-15-June), then Extra Usage
Interactive Claude Code (a real claude session — hand-driven, a long autonomous turn, /loop, or the sustained Mode 2.5 session)	Your local interactive claude client	Normal subscription allowance
Headless claude -p / Agent SDK	A local process, programmatically	Agent-SDK credit (post-15-June), then Extra Usage

The 15-June change: after 15-June, server-side claude_local runs draw on metered Agent-SDK credit (then Extra Usage). The whole point of cost-safe mode is to move model execution off that metered server path and onto the subscription you already pay for.

Why "operator mode" alone does NOT save money: driving agents from the CLI (agent wake, board prompt) only triggers work — the agent still executes server-side via claude_local → claude -p. Cheap CLI calls on the outside, expensive claude -p on the inside. The control plane moved; the engine didn't. The saving comes only from embodiment (your interactive session does the work) plus a non-executing adapter on the server.

The one rule that must never break

Never wake a claude_local agent server-side in a cost-safe company. That single action spawns claude -p and burns metered Agent-SDK credit. The cost-guard hook enforces this at runtime; embodiment on a non-executing (external, or process) adapter is the deliberate alternative.

The external adapter (paperclip-adapter-external on npm) is run-paperclip's default and a required instance-side dependency: it must be installed into your Paperclip instance, and your agents configured to use it as their adapter, for cost-safe operation to work at all. It runs no model server-side (mode:"webhook" POSTs a wake to the relay; mode:"noop" returns instantly) and additionally lets you author instructions/skills + mint a local agent JWT in the Paperclip UI. You don't set it up by hand — /pc-cost-safe installs it from npm (if the instance doesn't have it yet) and flips your agents onto it in one pass. The built-in process adapter is an equivalent no-model alternative.