OKAMI AGENTby OKAMI
// guides · 06

Paperclip heartbeat protocol

Paperclip is a control plane: it wakes Okami, injects env vars, assigns an issue and expects a status report with evidence. Okami works once per heartbeat instead o…

Open in full documentationGitHub

Heartbeat contract

  1. Read PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_RUN_ID and agent/company ids from env.
  2. Identify the agent with GET /api/agents/me.
  3. List assigned issues and choose by task id, status and priority.
  4. Checkout before work; 409 belongs to another agent and must not be retried.
  5. Run the harness once and report done, blocked, in_review or none.
okami paperclipchecks connection and prints agent/company metadata
okami heartbeatruns one heartbeat
okami heartbeat -a uiruns as the ui agent
okami heartbeat --mode deferturns sensitive actions into human confirmation interactions

Material evidence

To mark done, the report needs material evidence: changed files, commands/tests, URLs, hashes, code blocks or a structured handoff JSON. Without evidence, the issue stays in_review.

AutomationCron, hooks and heartbeat.ObservabilityDebugging a heartbeat.

Open this page in the interactive docs