live-task-pulse

name

live-task-pulse

description

Real-time task progress tracking with live push notifications. MANDATORY for ALL multi-step tasks (>30s or >2 tool calls). Activate automatically — do not wait for user to request it. Unique dual-layer architecture — file persistence for crash recovery + message tool push for real-time updates. Features step-based progress, stall detection (3min), auto-cleanup, and a Python CLI. Also triggers when user asks "what's running" / "task status" / "任务进度".

Live Task Pulse

Real-time task execution tracking with live push notifications.

Why This Exists

Other trackers write to files — users can't see progress until they ask. Live Task Pulse pushes every step change to the user's chat instantly via OpenClaw's message tool, while persisting state to JSON for crash recovery.

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│ task_pulse.py│───>│ JSON on disk │    │ User's chat │
│  (CLI tool)  │    │ (persistence)│    │ (Telegram/  │
└──────┬───────┘    └──────────────┘    │  Discord/..)│
       │                                └──────▲──────┘
       │         ┌──────────────┐              │
       └────────>│ message tool │──────────────┘
                 │ (real-time)  │
                 └──────────────┘

Dual-layer = no other skill does both.

Quick Reference

Create task → push start notification

TASK_ID=$(python3 scripts/task_pulse.py create "任务名" "步骤1" "步骤2" "步骤3")

Then immediately call message tool:

message(action="send", message="🚀 开始【任务名】\n📋 步骤1 → 步骤2 → 步骤3\n🔄 当前: 步骤1")

Advance to next step → push progress

python3 scripts/task_pulse.py next "$TASK_ID" "抓取了25条数据"

Then push: message(action="send", message="✅ [1/3] 步骤1完成（抓取了25条数据）\n🔄 → 步骤2")

Heartbeat (long step, >1min)

python3 scripts/task_pulse.py heartbeat "$TASK_ID" "已处理60%"

Push only if meaningful progress (avoid spam).

Complete

python3 scripts/task_pulse.py done "$TASK_ID" "发布成功 https://..."

Push: message(action="send", message="🎉 【任务名】完成！\n结果: https://...")

Fail

python3 scripts/task_pulse.py error "$TASK_ID" "登录过期"

Push: message(action="send", message="❌ 【任务名】失败\n错误: 登录过期")

Query status

python3 scripts/task_pulse.py status

Cleanup (>7 days completed)

python3 scripts/task_pulse.py cleanup

Mandatory Rules

1. Always push after file update — file update alone is invisible to users
2. Push format: emoji + [done/total] + current step + one-line info (≤3 lines)
3. Push frequency: every step transition; long steps max once per 30s
4. Stall = running + no update for 3 minutes — detected on status query
5. On stall detection: push ⚠️ 【任务名】可能卡住了（3分钟无更新）
6. Cleanup: run in heartbeat, keep completed tasks 7 days

Status Icons

Status	Icon	Meaning
running	🔄	Executing
done	✅/🎉	Completed
error	❌	Failed
stalled	⚠️	No update >3min
pending	⏳	Step not started

Integration

• Cron jobs: Wrap cron task payload with create/next/done calls
• Sub-agents: Parent agent creates task, sub-agent updates via file, parent pushes
• Heartbeat cleanup: Add python3 scripts/task_pulse.py cleanup to HEARTBEAT.md
• Multi-channel: message tool auto-routes to the active channel

See references/integration-guide.md for cron and sub-agent patterns.