Paperclip is a control plane, not an agent
You already know how to build a good harness: prompt, tools, skills, the loop itself. Paperclip sits one level above that loop. It does not decide how an agent thinks. It decides who works on what, when they wake up, how much they can spend, and whose sign-off they need.
“The control plane doesn't run agents. It orchestrates them. Agents run wherever they run and phone home.” What is Paperclip?
One idea: two layers
Control plane (Paperclip): a Node.js/Express server, React UI, and Postgres (an embedded database by default for local runs). It holds the org chart, tasks, budgets, goal hierarchy, approvals, and an audit trail.
Execution services (adapters): the agent's actual loop runs in Claude Code, Codex, Cursor, a shell process, an HTTP webhook, and so on. An adapter is the plug between the two.
The README states it bluntly: “Not an agent framework. We don't tell you how to build agents. We tell you how to run a company made of them.” Its tagline: “If OpenClaw is an employee, Paperclip is the company.”
README: What Paperclip is not · Architecture
The core model in six nouns
| Noun | What it is | Why it matters to you |
|---|---|---|
| Company | Top-level boundary with a goal, employees, budget, and task tree. Every entity is company-scoped. | Isolation: many companies per deployment. |
| Agent | An “employee” with an adapter + config, a role, one manager (a strict tree; the CEO reports to the board), and a monthly budget. | Escalation and delegation follow the org chart. |
| Issue (= task) | Unit of work with one assignee, a parent, and a project/goal link. Lifecycle: backlog → todo → in_progress → in_review → done, plus blocked and cancelled. | Goal ancestry: the agent always sees the “why”. |
| Heartbeat | A short execution window. Agents don't run continuously; they wake on a schedule, an assignment, an @-mention, a manual invoke, or an approval result. | Predictable cost and a transcript per run. |
| Adapter | A package whose server module exposes execute(ctx): spawn or call the runtime, capture output, usage, and session state. | Bring your own agent (“if it can receive a heartbeat, it's hired”). |
| Governance | The human “board” approves CEO strategy and agent hires (a configurable gate), can pause or terminate any agent, and budgets hard-stop at 100%. | Autonomy is granted, not assumed. |
Core Concepts · statuses in source: ISSUE_STATUSES · adapter contract: ServerAdapterModule.execute
What one heartbeat looks like
trigger (schedule | assignment | @-mention | manual | approval)
→ server calls adapter.execute() with PAPERCLIP_* env + prompt
→ agent runtime (e.g. Claude Code CLI) runs its own loop
→ agent calls Paperclip REST API:
GET /api/agents/me (who am I?)
GET …/issues?assigneeAgentId=me (my inbox)
POST /api/issues/{id}/checkout (claim it, or 409)
… do the work …
PATCH /api/issues/{id} status + comment
→ adapter captures stdout, usage/cost, session state
→ server stores the run record (audit + resume next time)
The key trick is atomic checkout. In the source it is a single conditional UPDATE issues … WHERE status IN (expected) AND (assignee IS NULL OR is me) AND no live execution lock. If another run owns the issue, the server throws a conflict (HTTP 409). The injected skill tells agents: “Never retry a 409.”
Heartbeat Protocol · checkout UPDATE · conflict throw · skills/paperclip/SKILL.md
Retrieval practice
Q1. A heartbeat fires for a claude_local agent. Where does the agent's model loop actually run?
Q2. Two agents call POST /api/issues/{id}/checkout on the same todo issue at the same moment. What happens?
Q3. Per the heartbeat protocol, what is an agent's first step on every wake?
Q4. According to the README, which setup probably does not need Paperclip?
Fit check (2 minutes, no right answer)
Think of the agent work you run today (parallel coding sessions, cloud agents, CI bots). For each one, answer in a line:
- Where does double-work happen? (Paperclip's answer: atomic checkout.)
- Where does an agent lose the “why”? (Paperclip's answer: parent/goal ancestry on every issue.)
- Where could a loop burn money unnoticed? (Paperclip's answer: per-agent budgets that pause at 100%.)
Bring the answers to your teacher. They will seed the fit verdict in your mission.
Primary source (read next)
Read Core Concepts (~10 min), then the Heartbeat Protocol. The protocol is the real contract between Paperclip and any agent you plug in, so read it as a harness engineer.
Ask your teacher
This lesson is a starting point, not the whole story. If anything is unclear, or you want to go deeper, ask me follow-up questions in chat. For example: “walk me through execute() in the claude-local adapter”, “how does session persistence survive between heartbeats?”, or “would atomic checkout fix our parallel-agent collisions?”