Heartbeats & Routines
When you first hire a few agents, it's tempting to give each one a timer — "wake up every few minutes and see if there's anything to do." It feels proactive. In practice, it's the fastest way to end…
Heartbeats & Routines
When you first hire a few agents, it's tempting to give each one a timer — "wake up every few minutes and see if there's anything to do." It feels proactive. In practice, it's the fastest way to end up with a sidebar full of paused agents, surprise token bills, and a dashboard you have to fight with just to keep things quiet.
Paperclip is designed around a different default: agents stay dormant until real work arrives. This guide explains the two mechanisms that drive an agent — heartbeats on an interval and routines — and when to reach for each one. It also walks through the Routines UI, from the list view down to the detail page where you configure triggers, variables, and run history.
---
The two ways an agent starts running
An agent can be woken up in four ways:
| Source | What triggers it | |---|---| | Timer | A heartbeat interval ticks (e.g. every 5 minutes, whether or not there's work) | | Assignment | A task is assigned to the agent, or a new comment arrives on one of its open tasks | | On demand | You click "Wake now" in the UI, or another agent hands it work | | Automation | A routine fires on its schedule and hands the agent an issue to execute |
The first — timer — is the only one that wakes an agent without anything having actually happened. The other three are event-driven: the agent runs because there's something to do, not in case there's something to do.
---
Why timer heartbeats are opt-in