mightyprime1_task-status/references/usage.md

Task Status Usage Guide

Quick Examples

Manual Status Updates (Single Messages)

# Progress update
python send_status.py "Fetching data..." "progress" "fetch"

# Success update
python send_status.py "Done! 150 records processed" "success" "process"

# Error update
python send_status.py "Failed to connect to API" "error" "api_call"

# Warning update
python send_status.py "Continuing despite timeout" "warning" "timeout"

Automated Periodic Monitoring (Every 5 seconds)

# Start monitoring a long task
python monitor_task.py start "video_processing" "progress"

# Monitor runs in background, sending "Still working..." updates every 5 seconds

# Stop monitoring with final status
python monitor_task.py stop "video_processing" "success" "Processing complete!"

# Or with an error
python monitor_task.py stop "video_processing" "error" "Failed: Corrupt file"

Python Script

from send_status import send_status

def process_data():
    send_status("Reading files...", "progress", "read")
    # ... work
    send_status("Processing complete", "success", "process")

Shell Script

#!/bin/bash
python send_status.py "Starting backup..." "progress" "backup"
# ... backup command
python send_status.py "Backup complete" "success" "backup"

Status Types

Type	Emoji	ASCII	When to Use
progress	🔄	->	Ongoing work, "still working on it"
success	✅	OK	Task completed successfully
error	❌	!	Task failed, cannot continue
warning	⚠️	?	Issue but continuing

When to Use Each Method

Use Manual Updates When:

• Task is short (under 30 seconds)
• You want control over when updates are sent
• Task has discrete, meaningful milestones

Use Periodic Monitoring When:

• Task is long-running (over 1 minute)
• You want consistent "heartbeat" updates every 5 seconds
• Task has long periods of quiet work
• You want to reassure user that work is ongoing

Periodic Monitoring Details

Starting a Monitor

python monitor_task.py start "<task_name>" "<status_type>" [--interval <seconds>]

• Sends "Still working..." updates every 5 seconds by default
• Runs in background until stopped
• Can customize interval with --interval

Viewing Active Monitors

python monitor_task.py status

Cancelling All Monitors (Without Final Status)

python monitor_task.py cancel_all

Best Practices

1. Keep messages short - Under 140 characters
2. Be specific - Include step names for clarity
3. Update periodically - Every ~4 seconds for long tasks (or use monitoring)
4. Use details - Add extra context when needed
5. End with status - Always send final success/error

Common Patterns

Multi-step Task (Manual)

python send_status.py "Step 1/5: Validating input" "progress" "step1"
# ... step 1
python send_status.py "Step 2/5: Processing data" "progress" "step2"
# ... step 2
# ... etc
python send_status.py "All steps complete" "success" "final"

Long-Running Task (Automatic Monitoring)

# Start monitor before starting the task
python monitor_task.py start "data_migration" "progress"

# Run the actual task (can take minutes/hours)
# Monitor sends "Still working..." updates every 5 seconds

# When task finishes, stop monitor with final status
python monitor_task.py stop "data_migration" "success" "Migration complete: 5000 records"

With Details

python send_status.py "Uploading..." "progress" "upload" --details "File: report.pdf (2.4MB)"

Error Recovery

python send_status.py "Connection failed, retrying..." "warning" "retry"
# ... retry logic
if success:
    python send_status.py "Retry successful" "success" "retry"
else:
    python send_status.py "Retry failed, giving up" "error" "retry"

Long Task with Manual Control

# Start monitor
python monitor_task.py start "processing" "progress"

# ... do work ...

# Check status periodically
python monitor_task.py status

# When done, stop monitor
python monitor_task.py stop "processing" "success" "Finished!"

Integration

Import send_status for Python Scripts

from send_status import send_status

msg = send_status("Working...", "progress", "work")
print(f"Logged: {msg}")  # Output: "-> [work] Working..."

Use in Shell Scripts

#!/bin/bash
send_status() {
    python send_status.py "$1" "$2" "$3"
}

send_status "Starting process" "progress" "main"
# ... process
send_status "Done" "success" "main"

Automation with Clawdbot Cron

For scheduled tasks that need periodic status updates, use Clawdbot's cron feature.

Monitoring Use Cases

File Processing

python monitor_task.py start "file_proc" "progress"
# Process 1000 files (takes 10 minutes)
python monitor_task.py stop "file_proc" "success" "Processed 1000 files"

Data Sync

python monitor_task.py start "sync" "progress" --interval 10
# Sync databases (takes 5 minutes)
python monitor_task.py stop "sync" "success" "Sync complete"

API Calls

python monitor_task.py start "api_call" "progress"
# Make 1000 API requests
python monitor_task.py stop "api_call" "success" "All 1000 requests successful"