knownasnaffy 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
- Always push after file update — file update alone is invisible to users
- Push format: emoji +
[done/total]+ current step + one-line info (≤3 lines) - Push frequency: every step transition; long steps max once per 30s
- Stall = running + no update for 3 minutes — detected on
statusquery - On stall detection: push
⚠️ 【任务名】可能卡住了（3分钟无更新） - 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 cleanupto HEARTBEAT.md - Multi-channel:
messagetool auto-routes to the active channel
See references/integration-guide.md for cron and sub-agent patterns.