wotai-dev/woterclip/heartbeat-log

Heartbeat Log

Parse and summarize the WoterClip heartbeat log file (.woterclip/heartbeat-log.jsonl).

Log Format

Each line is a JSON object in one of two kinds, distinguished by type. Full field definitions live in ${CLAUDE_PLUGIN_ROOT}/references/beat-economics.md.

Issue line — one per issue worked. A line with no `type` key is an issue line, which is what makes every pre-contract line readable without migration:

{"heartbeat": 7, "timestamp": "2026-03-25T10:15:00Z", "issue": "#79", "persona": "backend", "duration_sec": 720, "status": "in_progress", "actions": ["committed a1b2c3d", "created sub-issue #83"]}

Beat line — one per beat, carrying the beat's cost and why it stopped:

{"type": "beat", "started_at": "2026-03-25T10:03:00Z", "ended_at": "2026-03-25T10:17:05Z", "beat_elapsed_sec": 845, "issues_worked": 2, "stop_reason": "time_ceiling"}

Treat a missing field as unavailable, never as zero. Lines written before this contract carry no duration_sec value and have no accompanying beat line. Render those as —; counting them as 0 would report a beat that ran for minutes as free, and would drag any average toward zero.

Procedure

Step 1: Read Log

Read .woterclip/heartbeat-log.jsonl. If missing or empty, report "No heartbeat history found."

Parse each line as JSON. Handle malformed lines gracefully (skip with warning).

Step 2: Summarize

Recent activity (default: last 10 issue lines — beat lines are excluded from this view; see the aggregate stats below for beat-level figures):

Heartbeat History
─────────────────
#7  10:15  backend   #79  In Progress  (12 min)
#6  09:45  backend   #81  Completed    (8 min)
#5  09:15  ceo       #80  Triaged      (4 min)

Aggregate stats (when asked for analytics or summary):

• Total issue lines, and total beats (count of beat lines)
• Heartbeats per persona (breakdown)
• Average duration per persona — over issue lines that carry `duration_sec` only, stating how many lines were excluded as unavailable
• Total and average beat_elapsed_sec across beat lines
• Stop-reason breakdown (how many beats hit time_ceiling vs issue_budget vs complete)
• Completion rate (completed / total)
• Most active issues (by heartbeat count)
• Blocked issues and duration blocked

Step 3: Filter Options

Support filtering when the user asks:

• By persona: "show backend heartbeats" → filter by persona field
• By issue: "show activity for #79" → filter by issue field
• By date range: "show today's heartbeats" → filter issue lines by timestamp and beat lines by started_at; beat lines carry no timestamp
• By status: "show blocked heartbeats" → filter by status

Notes

• The log file is append-only and informational — safe to truncate if it grows too large
• Heartbeat numbers are per-issue (derived from comments), not global sequence numbers
• Field definitions — including what duration_sec and beat_elapsed_sec each measure — are in ${CLAUDE_PLUGIN_ROOT}/references/beat-economics.md