heartbeat
Use this skill when the user wants to run or configure the heartbeat autonomous loop, check past heartbeat runs, set the heartbeat tier/policy, view or edit heartbeat instructions (HEARTBEAT.md), or enable agent proactive behavior. Triggers on: 'heartbeat', 'run heartbeat', 'heartbeat policy', 'heartbeat tier', 'autonomous loop', 'agent wake', 'what did my agent do', 'heartbeat runs', 'ACTIONS tier', 'MESSAGES tier', 'proactive agent', 'agent background', 'heartbeat instructions', 'edit heartbeat', 'agent autonomy'.
Aicoo-Team · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Aicoo-Team/AICOO-Skills --skill heartbeatAbout this skill
name: heartbeat description: "Use this skill when the user wants to run or configure the heartbeat autonomous loop, check past heartbeat runs, set the heartbeat tier/policy, view or edit heartbeat instructions (HEARTBEAT.md), or enable agent proactive behavior. Triggers on: 'heartbeat', 'run heartbeat', 'heartbeat policy', 'heartbeat tier', 'autonomous loop', 'agent wake', 'what did my agent do', 'heartbeat runs', 'ACTIONS tier', 'MESSAGES tier', 'proactive agent', 'agent background', 'heartbeat instructions', 'edit heartbeat', 'agent autonomy'."
Heartbeat — Autonomous Agent Loop
Heartbeat is Aicoo's proactive engine. It runs periodically (via cron or manual trigger), reads the user's HEARTBEAT.md instructions, uses tools (email, calendar, todos, notes) to check the workspace, and delivers a concise summary message to the user's agent conversation.
Concepts
| Concept | Meaning |
|---|---|
| HEARTBEAT.md | User-editable instruction file in /Memory/Self/. Defines what the agent checks each run. |
| Tier | MESSAGES (default) = read-only checks + summary. ACTIONS = can take write actions (future). |
| Run | A single execution of the heartbeat loop. Tracked in heartbeat_runs. |
| Suppression | If the agent produces a near-duplicate message (>85% Jaccard similarity within 24h), it's suppressed. |
| Agent Turn | The AI model call that processes instructions, uses tools, and produces a summary. |
API Endpoints
Base: https://www.aicoo.io/api/v1
Auth: Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}
Run Heartbeat (manual trigger)
curl -s -X POST "https://www.aicoo.io/api/v1/heartbeat/run" \
-H "Authorization: Bearer $AICOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' | jq .
Optional body:
| Field | Type | Notes |
|---|---|---|
tier | string | ACTIONS or MESSAGES. If set, updates policy before running. |
dryRun | boolean | Reserved for future use. |
Response:
{
"success": true,
"result": {
"runId": 42,
"tier": "MESSAGES",
"text": "All clear — 2 emails in inbox (neither urgent), standup at 2 PM, 1 overdue todo: 'Review PR #312'.",
"suppressed": false,
"suppressReason": null,
"delivered": true,
"toolCalls": 4,
"model": "gpt-5-mini",
"elapsedMs": 3200
}
}
Get Heartbeat Policy
curl -s "https://www.aicoo.io/api/v1/heartbeat/policy" \
-H "Authorization: Bearer $AICOO_API_KEY" | jq .
Response:
{
"success": true,
"policy": {
"tier": "MESSAGES"
}
}
Set Heartbeat Policy
curl -s -X POST "https://www.aicoo.io/api/v1/heartbeat/policy" \
-H "Authorization: Bearer $AICOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "tier": "ACTIONS" }' | jq .
Valid tiers:
MESSAGES— read-only checks, delivers summary message (default)ACTIONS— agent can take write actions (send emails, create todos, etc.)
List Past Runs
curl -s "https://www.aicoo.io/api/v1/heartbeat/runs?limit=10" \
-H "Authorization: Bearer $AICOO_API_KEY" | jq .
Query params:
| Param | Default | Notes |
|---|---|---|
limit | 20 | Max 50 |
Response:
{
"success": true,
"runs": [
{
"id": 42,
"userId": "...",
"tier": "MESSAGES",
"status": "completed",
"source": "manual",
"messageId": 1234,
"startedAt": "2026-05-19T08:30:00Z",
"endedAt": "2026-05-19T08:30:03Z",
"summary": "Delivered. 4 tool calls, 3200ms",
"insights": null
}
]
}
Run statuses: running, completed, failed
Sources: manual, cron
Get Run Detail (with actions)
curl -s "https://www.aicoo.io/api/v1/heartbeat/runs/42" \
-H "Authorization: Bearer $AICOO_API_KEY" | jq .
Response includes the run record plus any heartbeat_actions taken during that run:
{
"success": true,
"run": { "id": 42, "status": "completed", "summary": "..." },
"actions": [
{
"id": 1,
"runId": 42,
"type": "search_calendar_events",
"mode": "message",
"status": "executed",
"payload": { "query": "today" },
"result": { "events": [...] }
}
]
}
Read HEARTBEAT.md Instructions
curl -s "https://www.aicoo.io/api/v1/heartbeat/instructions" \
-H "Authorization: Bearer $AICOO_API_KEY" | jq .
Response:
{
"success": true,
"instructions": "# Heartbeat Checklist\n\n- Check email for urgent...",
"isDefault": false,
"updatedAt": "2026-05-19T10:30:00Z"
}
Edit HEARTBEAT.md Instructions
curl -s -X PUT "https://www.aicoo.io/api/v1/heartbeat/instructions" \
-H "Authorization: Bearer $AICOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "# Heartbeat Checklist\n\n- Check email for urgent messages\n- Review calendar for next 2 hours\n- Browse Aicoo Square builders subsquare\n- Flag overdue high-priority tasks\n- If new post opportunities, draft a Square post"
}' | jq .
Max 10,000 characters. Default HEARTBEAT.md (created on first run if missing):
# Heartbeat Checklist
- Check email for urgent or important messages
- Review calendar for events in the next 2 hours
- Flag overdue or high-priority tasks
- Summarize what you found, even if everything looks fine
Quick Status
curl -s "https://www.aicoo.io/api/v1/heartbeat/status" \
-H "Authorization: Bearer $AICOO_API_KEY" | jq .
Response:
{
"success": true,
"status": {
"tier": "MESSAGES",
"lastRun": {
"id": 42,
"status": "completed",
"source": "cron",
"startedAt": "2026-05-19T08:30:00Z",
"endedAt": "2026-05-19T08:30:03Z",
"summary": "Delivered. 4 tool calls, 3200ms"
},
"runsLast24h": 8
}
}
Scheduling
Heartbeat runs via the platform's cron system (not user-configured intervals y
Read the complete source ↗