Skip to main content
Octo doesn’t just respond to prompts — it can reach out proactively when something needs attention.

​
Heartbeat

A periodic timer (default every 30 minutes) that checks if there’s anything worth telling you.

​
How It Works

1

Phase 1: Cheap Check

A low-tier LLM reads .octo/persona/HEARTBEAT.md (your standing instructions) and recent context. It decides: is action needed?
2

Phase 2: Full Graph (if needed)

Only when Phase 1 says yes, the full supervisor graph is invoked. This keeps costs low — most heartbeat ticks are Phase 1 only.
3

Delivery

Results are delivered via CLI output and/or Telegram message. The HEARTBEAT_OK sentinel suppresses delivery when there’s nothing to say (no notification spam).

​
Configuration

HEARTBEAT_INTERVAL=30m                  # 30m, 1h, 60s, etc.
HEARTBEAT_ACTIVE_HOURS_START=08:00      # local time
HEARTBEAT_ACTIVE_HOURS_END=22:00        # local time

​
Standing Instructions

Edit .octo/persona/HEARTBEAT.md to tell Octo what to check for. Example: 
# Heartbeat Instructions

- Check if any scheduled tasks are overdue
- Monitor GitHub issues for new critical bugs
- Remind me about standup at 9:45 AM

​
Commands

CommandDescription
/heartbeatShow heartbeat status
/heartbeat testForce a heartbeat tick now

​
Cron Scheduler

A persistent job scheduler for recurring and one-shot tasks.

​
Job Types

TypeExampleDescription
atin 2h, 15:00One-shot, fires once
every30m, 1dRecurring interval
cron0 9 * * MON-FRI5-field cron expression

​
Commands

/cron                    # list all jobs
/cron add <spec> <task>  # schedule a new job
/cron remove <id>        # delete a job
/cron pause <id>         # pause without deleting
/cron resume <id>        # resume a paused job

​
Self-Scheduling

Agents can schedule their own follow-ups using the schedule_task tool. For example, a research agent might say: “I’ll check back in 2 hours to see if the API data has updated.” Jobs are stored in .octo/cron.json and survive restarts.
Combine heartbeat with cron for powerful workflows: use heartbeat for general monitoring and cron for specific scheduled tasks.