Heartbeats

Heartbeats are cron-driven agent spawns that run on a schedule without any user prompt. Use them for proactive maintenance, daily summaries, dependency audits, or self-improvement — where an agent reads recent sessions and writes new slash command skills to improve the team over time.

Configuration

Heartbeat settings live in .agenties/config.json under the heartbeat key. You can edit them directly or through Settings → Heartbeats in the UI.

config.json (heartbeat section)

{
  "heartbeat": {
    "enabled": true,
    "cronExpr": "0 9 * * 1-5",       // Every weekday at 9am
    "model": "claude-haiku-4-5",
    "effort": "low",
    "selfImprovement": false,
    "taskPrompt": "Check open issues, review recent commits, and post a brief status update."
  }
}

Cron expressions

Agenties uses standard 5-field cron syntax: minute hour day-of-month month day-of-week.

Expression	Schedule
`0 9 * * 1-5`	Weekdays at 9:00 AM
`/30 * * *`	Every 30 minutes
`0 /4 * *`	Every 4 hours
`0 8 * * 1`	Every Monday at 8:00 AM
`0 0 * * *`	Every day at midnight
`0 18 * * 5`	Every Friday at 6:00 PM (end-of-week summary)

Note:Heartbeats use your local machine's timezone. The cron schedule is evaluated by the Agenties renderer process, so heartbeats only fire while the app is open. For true background scheduling, use Routines with a schedule type — those fire from Agenties cloud automation even when the app is closed.

Self-improvement mode

When selfImprovement: true, the heartbeat agent receives additional context: the last 7 days of session summaries from your vault, your current slash command library, and a meta-prompt instructing it to identify workflow friction and write new skills.

What the agent can write

The self-improvement agent has write access to ~/.claude/commands/, which is where Claude Code loads custom slash commands. It can create, update, or delete skill files in this directory.

Self-improvement prompt (injected automatically)

You are a process improvement specialist for the Agenties workflow.

Recent session summaries (last 7 days):
<vault:sessions/...>

Current slash commands in ~/.claude/commands/:
<ls ~/.claude/commands/>

Your task:
1. Identify any repetitive manual steps from the session summaries.
2. For each, decide if a new slash command skill would eliminate the friction.
3. Write or update skill files in ~/.claude/commands/ as needed.
4. Post a brief summary of what you created/updated to the mailbox.

Safety guardrails

Self-improvement agents can only write to ~/.claude/commands/. They do not have access to your project files, vault notes outside the sessions/ directory, or any other system paths. Permission requests for anything outside this scope are automatically denied.

Warning:Review new slash commands created by self-improvement agents before using them in production. They are written by a Haiku-class agent with minimal context — they may be useful starting points but should be reviewed and potentially refined.

What the heartbeat agent does

A standard (non-self-improvement) heartbeat agent runs a configurable taskPrompt. Common use cases:

Daily standup

Read open issues, list_agents for recent activity, and post a brief standup to the mailbox to:user summarising what was done yesterday and what is open today.

Dependency audit

Check package.json for outdated dependencies using the shell tool. Open a new issue for any package that is more than 2 major versions behind.

End-of-week summary

Read all done issues closed this week and session notes from vault/sessions/. Write a summary to vault/sessions/YYYY-WW-weekly.md.

Health check

Run the test suite. If any tests fail, open a high-priority issue and post an alert to the mailbox.

Check interval

The renderer polls the cron schedule every minute using a setInterval in the Agenties window process. When the cron expression matches the current minute, a heartbeat spawn is triggered. The most recent heartbeat fire time is stored in config.json to prevent double-firing on rapid app restarts.

Heartbeat history

Every heartbeat run is logged in the Heartbeats panel (navigate with /heartbeats). You can see the run time, model used, token cost, and the full output stream. Heartbeat output is also posted as a status message to the mailbox and can be exported with /export.

← PreviousMailbox Next →Routines