Docs / Heartbeat mode

Heartbeat mode

Heartbeat mode enables autonomous, long-running agents that operate on a persistent assess → plan → act → persist → sleep cycle. Ideal for proactive monitoring, maintenance, and continuous-improvement tasks.

Overview

A heartbeat agent runs indefinitely, following this cycle:

1. Assess — evaluate the current state (check files, monitor systems, review logs).
2. Plan — determine what actions to take based on the assessment.
3. Act — execute planned actions using available tools.
4. Persist — save state to disk for resumability.
5. Sleep — wait for the configured interval, then repeat.

Quick start

# Run a heartbeat agent that checks every 5 minutes
ravenclaws --heartbeat --exec "Monitor the /tmp directory for new files and report changes"

Configuration

[heartbeat]
goal = "Monitor system health and report anomalies"  # Required: agent's mission
tick_interval_secs = 300    # Sleep between cycles (5 minutes)
max_ticks = 0               # 0 = unlimited
max_iterations_per_tick = 5 # Agent loop iterations per tick
enable_tools = true         # Enable tool calling
workdir = "/workspace"      # Working directory for state persistence

[llm]
provider = "openai"
model = "gpt-4o-mini"
system_prompt = "You are a vigilant system monitor. Assess, plan, and act carefully."

State persistence

Heartbeat agents automatically persist their state to disk after each cycle. This means:

• Survives restarts — if the agent is stopped and restarted, it resumes from the last checkpoint.
• Crash recovery — if the process crashes mid-cycle, state up to the last persist is preserved.
• Manual inspection — state files are human-readable JSON.

State file contents

{
  "cycle": 42,
  "last_assessment": "System healthy. 3 files changed since last check.",
  "last_plan": "Review changed files for security issues.",
  "last_action": "Scanned 3 files. No issues found.",
  "timestamp": "2026-06-02T15:30:00Z"
}

Use cases

File system monitoring

ravenclaws --heartbeat \
  --system-prompt "You are a file integrity monitor." \
  --exec "Monitor /etc for unauthorized changes. Alert if any file is modified."

Log analysis

ravenclaws --heartbeat \
  --system-prompt "You are a log analyst." \
  --exec "Check /var/log for error patterns every minute. Summarize new errors."

CI/CD health monitor

ravenclaws --heartbeat \
  --system-prompt "You are a CI/CD health monitor." \
  --exec "Check GitHub Actions workflow status every 10 minutes. Report failures."

Best practices

1. Set appropriate intervals — don't poll too frequently (respect rate limits).
2. Use specific system prompts — focus the agent on its monitoring role.
3. Enable audit logging — track all actions for compliance.
4. Configure the sandbox — restrict file system access to necessary paths.
5. Monitor the monitor — use health endpoints to verify the heartbeat is running.
6. Test recovery — verify state persistence works by restarting the agent.