How Paperclip Works — Core Workflow

The end-to-end daily-use loop: create company → hire agents → seed tasks → heartbeats fire → agents pick up tasks → review outputs → iterate. Builds the mental model before any code.

How Paperclip Works — Core Workflow

What you'll learn

By the end of this lesson you'll understand the complete daily-use loop in Paperclip AI — from creating a company through to reviewing agent outputs — before touching any code.

The six-stage loop

Every interaction with Paperclip follows the same repeating cycle:

1. Create Company
       ↓
2. Hire Agents
       ↓
3. Seed Issues (tasks)
       ↓
4. Heartbeats Fire  ←─────────────────┐
       ↓                               │
5. Agents Work                         │
       ↓                               │
6. Review Outputs ──────── iterate ────┘

Once you reach stage 4, the loop runs automatically on a schedule. Your job as the operator shifts from "doing work" to "reviewing work and adjusting direction."

Stage 1 — Create a Company

A Company is the top-level container for everything in Paperclip. All agents, tasks, costs, and logs belong to exactly one company. Think of it as a separate workspace or tenant.

You create a company with a name and a timezone. The timezone drives when daily heartbeat windows fire.

Stage 2 — Hire Agents

An Agent is a named worker with a role, a system prompt, and an adapter that tells Paperclip how to actually run it (Claude Code CLI, OpenAI API, a webhook, or a shell script).

When you "hire" an agent a human approval gate fires first — you have to confirm the hire. This is intentional: agent creation is a consequential action with real cost implications.

Stage 3 — Seed Issues

Issues are tasks. They have a title, a description, a status (open → in_progress → completed), and optionally a parent issue for nesting subtasks.

You can create issues manually, bulk-import them via the API, or have a manager agent create them for worker agents to pick up.

Stage 4 — Heartbeats Fire

A heartbeat is a scheduled trigger that wakes each agent according to its cron schedule. When a heartbeat fires for an agent, Paperclip:

1. Checks the agent isn't already running (concurrency lock)
2. Checks the agent's monthly budget hasn't been exceeded
3. Selects the highest-priority open issue assigned to the agent
4. Calls adapter.invoke(issue) — the adapter runs the actual AI work

Stage 5 — Agents Work

The adapter does the work. For a Claude Code adapter this means spawning the claude CLI with the issue as context. For an OpenAI adapter it means calling the chat completions API. For an HTTP adapter it means POSTing to an external endpoint.

The adapter returns a runId. Paperclip polls adapter.status(runId) until the run completes, then captures the output and records the token cost.

Stage 6 — Review Outputs

After each heartbeat run, Paperclip writes:
- A heartbeat_runs record with status, duration, token count, and cost
- A cost_event with the USD amount charged
- An activity_log entry describing what happened

You review these in the dashboard, check whether the agent moved issues forward, and decide whether to adjust the agent's prompt, add more tasks, or change the schedule.

Key mental model

Paperclip is a control plane, not an execution engine. It decides what agents work on and when — the actual intelligence lives inside the adapters (Claude, GPT, your own code).

Checkpoint ✓

• What are the 6 stages of the Paperclip loop?
• What is a heartbeat?
• What is the difference between a Company, an Agent, and an Issue?
• What does an adapter do?