The heartbeat system controls whether and how an agent restarts after it stops. By default, agents run in manual mode — they stop when they’re done and wait for you to intervene. Other modes let agents restart automatically, run on intervals, or follow a schedule.
Modes
| Mode | Display Name | Description | Use Case |
|---|
manual | Manual | Agent only runs when you explicitly start it. | One-off tasks, exploratory work |
alwaysOn | Always On | Agent restarts automatically if it stops. Best for critical, always-running agents. | Monitoring, continuous review, long-running services |
interval | Interval | Agent wakes up periodically to check for work. | Polling for changes, periodic code sweeps |
scheduled | Scheduled | Agent runs on a cron schedule for predictable execution windows. | Daily reports, nightly builds, scheduled maintenance |
Configuring
Open the Heartbeat tab in the Detail Panel to set an agent’s heartbeat mode. Select a mode and configure its parameters.
Mode Details
Manual (Default)
The agent runs when you start it and stops when it finishes or you terminate it. No automatic restarts. This is the default for all new agents.
Always On
The agent restarts automatically whenever it stops — whether it finished its task, crashed, or was interrupted.
| Parameter | Default | Description |
|---|
| Max retries | 3 | Maximum consecutive restart attempts before giving up |
| Restart delay | 30 seconds | Wait time between restart attempts |
error state and stops restarting. Reset the retry counter by manually restarting the agent.
Always On agents consume API credits continuously. Each restart begins a new Claude Code session that incurs token costs. Use this mode only for agents that genuinely need to run without interruption.
Interval
The agent wakes up periodically, checks for work (reads its TASKS.md), and runs until it finishes or has nothing to do. Then it sleeps until the next interval.
| Parameter | Default | Description |
|---|
| Interval seconds | — | Time between wake-ups (e.g., 300 for every 5 minutes) |
Scheduled
The agent runs on a cron schedule. Configure a cron expression to define when the agent should start.
| Parameter | Default | Description |
|---|
| Cron expression | — | Standard cron syntax (e.g., 0 9 * * 1-5 for weekdays at 9am) |
| Active hours start | — | Optional start of active window |
| Active hours end | — | Optional end of active window |
Scheduled mode is available for configuration but execution is currently deferred. Agents can be configured with cron expressions in preparation for future scheduling support.
heartbeat-config.json
The heartbeat configuration is stored as a JSON file in the agent’s identity directory:
{
"mode": "alwaysOn",
"intervalSeconds": null,
"cronExpression": null,
"activeHoursStart": null,
"activeHoursEnd": null,
"maxRetries": 3,
"restartDelaySeconds": 30
}
The Heartbeat + Soul + Tasks Pattern
The heartbeat system is most powerful when combined with a well-defined soul and task list:
- Soul defines the agent’s role and constraints — who it is
- Tasks define the current work items — what to do
- Heartbeat defines the schedule — when to run
Example: A review agent that checks for PRs every 15 minutes:
- Soul: “You are a code reviewer. Review open PRs for security issues and test coverage.”
- Tasks: “Check for new PRs. Review each one. Post comments.”
- Heartbeat: Interval mode, 900 seconds
Each time the agent wakes up, it reads its soul (who am I?), checks its tasks (what should I do?), does the work, and goes back to sleep until the next interval.
Related Pages
- Agents — agent lifecycle and identity files
- Souls — defining agent identity
- Tasks — assigning work items
- Memory — persistent context
