grandamenium Heartbeat
The heartbeat is how the dashboard and other agents know you are alive. If you stop updating it, you appear DEAD.
Your Heartbeat Cron
Your heartbeat cron is daemon-managed (default every 4h). It lives in ${CTX_ROOT}/state/${CTX_AGENT_NAME}/crons.json and fires even after restarts — no manual restoration needed. When it fires:
# 1. Update your heartbeat with what you're doing
cortextos bus update-heartbeat "WORKING ON: <current task summary>"
# 2. Check inbox for messages
cortextos bus check-inbox
# 3. Log heartbeat event
cortextos bus log-event heartbeat agent_heartbeat info \
--meta "{\"agent\":\"$CTX_AGENT_NAME\",\"status\":\"active\"}"
# 4. Check your task queue for anything stale
cortextos bus list-tasks --agent $CTX_AGENT_NAME --status in_progress
Updating Heartbeat
cortextos bus update-heartbeat "<one sentence: what you are doing right now>"
Call this:
- On every heartbeat cron fire
- On session start (before sending online notification)
- When starting a new significant task
- Before going into a long-running operation
Never claim a status you haven't verified. To confirm your crons are active: cortextos bus list-crons $CTX_AGENT_NAME (shows each cron's next_fire_at). Crons are daemon-managed and survive restarts — if a cron is missing, add it via cortextos bus add-cron.
Reading Fleet Heartbeats
# All agents in the org
cortextos bus read-all-heartbeats
# JSON format for parsing
cortextos bus read-all-heartbeats --format json
Returns: agent name, status, last update timestamp, current task.
Stale threshold: An agent that hasn't updated in >6h should be investigated. Check their status via cortextos status or their heartbeat file.
Checking a Specific Agent
# Read their heartbeat file directly
cat "$CTX_ROOT/state/<agent-name>/heartbeat.json"
# Check agent status via daemon
cortextos status
# Check PM2 process status
pm2 list
Heartbeat File Schema
{
"agent": "agent-name",
"status": "active | idle | crashed",
"timestamp": "2026-04-01T12:00:00Z",
"current_task": "What I'm doing right now"
}
Location: $CTX_ROOT/state/{agent}/heartbeat.json