Scheduling

NanoFleet agents support two types of scheduled execution: heartbeat (periodic check-in) and cron jobs (time-based tasks — not yet implemented).

Heartbeat

The heartbeat is a periodic self-check. If HEARTBEAT.md exists in the workspace and is non-empty, the agent runs through it at the configured interval.

HEARTBEAT.md

Write a checklist of periodic tasks for the agent to review:

- Check for new GitHub issues assigned to me
- Review open pull requests and leave comments if needed
- Update MEMORY.md with any new context
- Post a summary to Telegram if anything needs attention

The agent reads this file, works through the items, and may proactively send notifications to connected channels.

Configuration

Set the interval (in seconds) via environment variable:

HEARTBEAT_INTERVAL=1800  # default: 1800 seconds (30 minutes)

If HEARTBEAT.md is empty or doesn’t exist, the heartbeat is silently skipped — no LLM call is made.

Cron jobs

Not yet implemented. Cron job scheduling is planned for a future release. Use HEARTBEAT.md for periodic tasks in the meantime.

When implemented, cron jobs will be declared in cron.json in the workspace:

[
  {
    "name": "morning-briefing",
    "cron": "0 9 * * 1-5",
    "timezone": "Europe/Paris",
    "message": "Prepare a morning briefing with today's priorities from the task board and send it to the Telegram channel."
  }
]

Field	Required	Description
`name`	Yes	Unique job identifier
`cron`	Yes	Cron expression (5 fields)
`timezone`	No	IANA timezone (default: `UTC`)
`message`	Yes	Instruction sent to the agent

Heartbeat vs cron

	Heartbeat	Cron
Trigger	Fixed interval	Time expression
Status	Available	Not yet implemented
Skip if empty	Yes	No (runs task string)

Proactive notifications

When a scheduled task completes, the agent can push messages to connected channels without waiting for a user message.

The flow:

Heartbeat run completes with actionable output
Agent emits a notification via an internal SSE stream
Connected channel picks it up and delivers it to the user (Telegram, Discord, etc.)

If no channel is connected when the notification is emitted, it is silently dropped.