routines

Routines — Recurring Agent Tasks

Routines are Paperclip's scheduling primitive. Instead of agents burning tokens on timer heartbeats polling for work, routines fire only when needed — on a cron schedule, webhook, or explicit API call — and create a targeted heartbeat run for the assigned agent.

Why Routines > Always-On Heartbeats

The key insight: clean up heartbeats = token reducing = cheaper.

Quick Start

1. Find your IDs

# Company ID
curl -s "$PAPERCLIP_API_URL/api/agents/me" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq '.companyId, .id'

# Agents in company
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/agents" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq '.[] | {id, name, role}'

# Projects
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/projects" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq '.[] | {id, name}'

2. Create a routine

curl -s -X POST "$PAPERCLIP_API_URL/api/companies/{companyId}/routines" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily standup check",
    "description": "CEO reviews all in_progress issues and nudges stalled agents",
    "assigneeAgentId": "{ceo-agent-id}",
    "projectId": "{project-id}",
    "priority": "medium",
    "status": "active",
    "concurrencyPolicy": "skip_if_active",
    "catchUpPolicy": "skip_missed"
  }'

3. Add a cron trigger

curl -s -X POST "$PAPERCLIP_API_URL/api/routines/{routineId}/triggers" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "schedule",
    "cronExpression": "0 9 * * 1-5",
    "timezone": "Europe/Amsterdam"
  }'

4. Or add a webhook trigger (for external events)

curl -s -X POST "$PAPERCLIP_API_URL/api/routines/{routineId}/triggers" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "webhook",
    "signingMode": "bearer"
  }'

The response includes a publicId and signing secret. External systems POST to: POST /api/routine-triggers/public/{publicId}/fire

5. Manual run (testing)

curl -s -X POST "$PAPERCLIP_API_URL/api/routines/{routineId}/run" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "manual"}'

Suggested Routine Patterns

CEO Agent

Engineer Agent

PM Agent

Cross-cutting

Concurrency Policies

Choose based on routine behavior:

Catch-Up Policies

Managing Routines

# List all routines
curl -s "$PAPERCLIP_API_URL/api/companies/{companyId}/routines" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq '.[] | {id, title, status, assigneeAgentId}'

# Pause a routine
curl -s -X PATCH "$PAPERCLIP_API_URL/api/routines/{routineId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

# Resume
curl -s -X PATCH "$PAPERCLIP_API_URL/api/routines/{routineId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

# Archive (permanent)
curl -s -X PATCH "$PAPERCLIP_API_URL/api/routines/{routineId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

# Check run history
curl -s "$PAPERCLIP_API_URL/api/routines/{routineId}/runs?limit=10" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq '.[] | {id, status, createdAt}'

# Update trigger schedule
curl -s -X PATCH "$PAPERCLIP_API_URL/api/routine-triggers/{triggerId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cronExpression": "0 10 * * 1-5"}'

# Disable a trigger without deleting
curl -s -X PATCH "$PAPERCLIP_API_URL/api/routine-triggers/{triggerId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Delete a trigger
curl -s -X DELETE "$PAPERCLIP_API_URL/api/routine-triggers/{triggerId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Webhook Integration Examples

GitHub → Engineer wake on push

1. Create routine with webhook trigger
2. In GitHub repo settings → Webhooks, add:
   • URL: {PAPERCLIP_PUBLIC_URL}/api/routine-triggers/public/{publicId}/fire
   • Content type: application/json
   • Events: Push, Pull request
   • Secret: the signing secret from trigger creation

Railway → Engineer wake on deploy

Same pattern — Railway supports deploy webhooks that POST to your routine trigger URL.

Agent Access Rules

Migration: Heartbeat → Routines

To convert an always-on heartbeat agent to routine-based:

1. Identify the agent's recurring tasks from their HEARTBEAT.md
2. Create a routine for each distinct recurring concern (standup, triage, deploy check, etc.)
3. Add appropriate triggers — cron for time-based, webhook for event-based
4. Reduce or stop the heartbeat interval — routines handle the scheduling now
5. Keep one low-frequency fallback heartbeat (e.g., every 2 hours) as a safety net for anything routines don't cover
6. Monitor run history to verify routines fire correctly before fully removing heartbeats

Full API Reference

See skills/paperclip/references/api-reference.md for the complete endpoint list and the Routines API doc at docs/api/routines.md in the Paperclip source.