Paperclip agents don't run continuously. They wake on a schedule, check their assigned work, execute through their adapter, and go back to sleep. That cycle is called a heartbeat.
This matters for three reasons. First, cost: agents only burn tokens during active heartbeats, not 24/7. Second, context: sessions persist between heartbeats, so agents pick up where they left off instead of re-reading everything from scratch. Third, control: you decide exactly when and how often each agent works. No surprises on your API bill, no agents going rogue at 3am.
Master paperclip heartbeats & scheduled execution
Take the Paperclip Fundamentals course with hands-on lessons and challenges.
heartbeat.intervalMinutes controls how often the agent wakes up. Set enabled to false to pause the agent without deleting it. The monthly budget acts as a hard ceiling -- even running every 15 minutes, this agent can't spend more than $30/month on tokens.
Five steps, every time. The atomic checkout in step 2 is what prevents two agents from grabbing the same issue. And session persistence in step 4 is why agents can work on multi-step tasks across heartbeats without losing their place.
The runs API gives you the full heartbeat history -- timing, token usage, costs, outcomes. Notice the SKIPPED run: the agent woke up, checked its backlog, found nothing to do, and went back to sleep. If you see a lot of those, the agent either needs more work or a longer heartbeat interval.
These environment variables tell the agent runtime everything it needs: who it is, which company it belongs to, what run it's executing, and how to talk back to Paperclip. The session ID is what makes continuity work -- the runtime uses it to resume its previous state.
Setting heartbeat intervals too short (every 1-2 minutes) for agents that don't need real-time responsiveness, burning through budgets on idle checks
Match the interval to the role. Code review agents? Every 30 minutes is fine. Strategy agents? Once a day. If something is truly urgent, use event-based triggers instead of cranking up the heartbeat frequency.
Setting clearSession to true after every heartbeat, forcing the agent to restart its context from scratch each time
Leave clearSession as false unless you have a specific reason. Session continuity is the whole point -- without it, your agent re-reads the entire codebase every heartbeat, which wastes time and tokens.
Ignoring SKIPPED runs in the heartbeat history and missing the signal that an agent has nothing to do
Watch the COMPLETED-to-SKIPPED ratio. If an agent is skipping most of its heartbeats, its backlog is empty. Either give it more work, slow down its heartbeat, or pause it. No point paying for an agent to wake up and go back to sleep.
Not setting monthly budgets and letting a misconfigured agent spend unlimited tokens
Always set a monthlyBudget. Paperclip enforces it atomically -- once the budget is gone, heartbeats get throttled. Start low and raise it based on what you actually see the agent spending.
Heartbeats are how Paperclip agents work: wake up, grab an issue, do the work, report back, go to sleep. You get cost control (agents only spend tokens when they're actually running), context continuity (sessions persist across heartbeats), and predictable scheduling. The practical advice: start with longer intervals, use event triggers for anything time-sensitive, always set monthly budgets, and keep an eye on your SKIPPED-to-COMPLETED ratio to know when agents need more work or less frequent heartbeats.
Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.
Interactive lessons and challenges, right in your code editor.
Check the free courses. No credit card.