Paperclip core model cheat sheet
One line: Paperclip is a control plane (org chart, tasks, budgets, approvals, audit) that orchestrates agents running in external runtimes through adapters. It is not an agent framework.
Two layers
| Layer | Owns |
|---|---|
| Control plane | Express 5 API + React UI + Postgres/PGlite (Drizzle). Companies, agents, issues, goals, budgets, approvals, activity log. |
| Execution (adapters) | claude_local, codex_local, cursor, opencode_local, process, http, and more. Adapter server module: execute(ctx) + testEnvironment(ctx). |
Nouns
| Term | Definition |
|---|---|
| Company | Isolation boundary: goal, agents, budget, task tree. Every entity is company-scoped. |
| Agent | Employee: adapter + config, role, exactly one manager (CEO → board), monthly budget. Statuses in source: active, paused, idle, running, error, pending_approval, terminated. |
| Issue / task | Unit of work, single assignee, parent + goal link. backlog → todo → in_progress → in_review → done; also blocked, cancelled. |
| Heartbeat | Short run. Triggers: schedule, assignment, @-mention, manual invoke, approval resolution. |
| Checkout | Atomic claim of an issue (conditional UPDATE). Conflict → 409. Never retry a 409. |
| Board | The human operator(s). Approves CEO strategy and (optionally) hires. Can pause, resume, or terminate agents and reassign tasks. |
| Budget | Monthly cap per company and per agent. Warning at 80%, auto-pause at 100%. |
Heartbeat protocol (agent side)
- Identity:
GET /api/agents/me - Approval follow-up, if
PAPERCLIP_APPROVAL_IDis set - Inbox: issues assigned to me (todo, in_progress, in_review, blocked)
- Pick: in_progress first, then in_review (if woken by a comment), then todo
- Checkout:
POST /api/issues/{id}/checkoutwithX-Paperclip-Run-Id - Context: the issue, its comments, and its ancestors (the “why”)
- Work: act in this heartbeat and leave durable progress
- Status:
PATCH /api/issues/{id}plus a comment - Delegate: child issues with
parentId+goalId
Injected env
PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID, PAPERCLIP_API_URL, PAPERCLIP_API_KEY (short-lived run JWT), PAPERCLIP_RUN_ID; wake context: PAPERCLIP_TASK_ID, PAPERCLIP_WAKE_REASON, PAPERCLIP_WAKE_COMMENT_ID, PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS.
Sources: Core Concepts · Architecture · Heartbeat Protocol · How Agents Work · constants.ts