Paperclip explained: an operating layer for teams of AI agents
Paperclip architecture: from issue to heartbeat and receipt
Trace the control path that turns a board task into an agent run.
What you will learn
- The board supplies intent
- The runtime supplies execution
- Governance closes the loop
Before you start
- Node.js and agent runtime basics
- A test company with non-sensitive tasks
Turn the source review into a bounded experiment with stop conditions.
Key takeaways
- A heartbeat is a control-plane event.
- A completed run is not automatically accepted work.
- Issue and run identifiers make the chain auditable.
The board supplies intent
A goal and issue identify what should be done, while org roles determine who may take it. The README describes scheduling and event-based triggers that queue wakeups. Keep the issue ID attached to every run record.
A heartbeat should resolve an eligible task before invoking an adapter. If two agents act on the same item, investigate claim and scheduling behavior rather than blaming the final model response.
The runtime supplies execution
The documented execution path checks budgets, resolves a workspace, injects scoped secrets and invokes the selected adapter. Logs, cost events and session state become evidence about what happened.
These components create several failure points: no queued work, wrong workspace, missing credential or adapter error. A run can be technically complete while producing unusable work.
Governance closes the loop
Approvals, comments and audit events let a reviewer inspect an output before another action. A budget threshold may pause work; it does not decide whether a draft is correct.
The diagram is an architectural reading of the README and service files. It is not a distributed trace captured from a running deployment.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Pick one issue and identify its intended owner.
- 2
Trace enqueue, adapter invocation and cost event in local logs.
- 3
Link the output and approval back to the issue.
Copy-ready example
issue -> wakeup queue -> budget/workspace checks -> adapter run
run -> logs + cost event -> review/approvalFrequently asked questions
Where does the actual model execute?
In the connected agent runtime selected by an adapter; Paperclip coordinates its work.
Does a heartbeat always start new work?
It can find no eligible task or be held by policy; inspect the queue and state.
Sources
- Paperclip / README.mdSource checked 2026-09-26
- Paperclip / server/src/services/approvals.tsSource checked 2026-09-26
- Paperclip / server/src/services/budgets.tsSource checked 2026-09-26