hour-meter – OpenClaw Skill

---

name: hour-meter clawhub: tardis description: Track elapsed time from a set epoch with tamper-evident locking. Like an analog Hobbs meter but digital. Use for tracking uptime, service hours, time since events, sobriety counters, project duration, equipment runtime. Supports create, lock (seal), check, verify against external hash, list, and export operations.

Hour Meter (TARDIS on ClawHub)

Life event tracker with three modes, milestone notifications, and tamper-evident verification.

ClawHub Note: This skill is published as TARDIS on ClawHub after the original hour-meter listing was lost due to a repository sync issue.

Three Modes

COUNT UP — Time since an event

# Quit smoking tracker
meter.py create smoke-free --start "2025-06-15T08:00:00Z" -d "Last cigarette"
meter.py milestone smoke-free -t hours -v 720 -m "🎉 30 days smoke-free!"
meter.py lock smoke-free  # → Gives you paper code to save

COUNT DOWN — Time until an event

# Baby due date
meter.py create baby --start "2026-01-15" --end "2026-10-15" --mode down -d "Baby arriving!"
meter.py milestone baby -t percent -v 33 -m "👶 First trimester complete!"

COUNT BETWEEN — Journey from start to end

# Career span
meter.py create career --start "1998-05-15" --end "2038-05-15" -d "40-year career"
meter.py milestone career -t percent -v 50 -m "📊 Halfway through career!"
meter.py career --meter career --rate 85 --raise-pct 2.5

Tamper-Evident Persistence

When you lock a meter, you get a paper code — a short, checksummed code you can write on paper:

╔══════════════════════════════════════════════════════════════╗
║  PAPER CODE (write this down):                               ║
║     318B-3229-C523-2F9C-V                                    ║
╚══════════════════════════════════════════════════════════════╝

Four Ways to Save (Non-Technical)

1️⃣ PAPER — Write the code on paper/sticky note

• 20 characters with dashes, easy to copy
• Built-in checksum catches typos when verifying
• Keep in wallet, safe, or taped to equipment

2️⃣ PHOTO — Screenshot or photograph the lock screen

• Store in camera roll, cloud photos
• Visual backup, no typing required

3️⃣ WITNESS FILE — Auto-saved to ~/.openclaw/meter-witness.txt

• Append-only log of all locked meters
• Sync folder to Dropbox/iCloud/Google Drive for cloud backup
• Contains paper code + full hash + timestamp

4️⃣ EMAIL TO SELF — Click the mailto: link or copy the one-liner

• Opens your email client with pre-filled subject and body
• Or copy the compact message: 🔒 my-meter | Code: XXXX-XXXX-XXXX-XXXX-C | Locked: 2026-02-02
• Send to yourself, search inbox later to verify

5️⃣ SENDGRID EMAIL — Auto-send verification email on lock

# Set your SendGrid API key
export SENDGRID_API_KEY=SG.xxxxx
export SENDGRID_FROM_EMAIL=verified@yourdomain.com

# Lock and email in one command
meter.py lock my-meter --email you@example.com

• Sends a beautifully formatted HTML email with paper code
• Requires a verified sender in SendGrid (see SendGrid docs)
• Great for automated workflows

Verifying Later

# With paper code (catches typos!)
meter.py verify my-meter "318B-3229-C523-2F9C-V"

# → ✅ VERIFIED! Paper code matches.
# → ⚠️ CHECKSUM ERROR! (if you have a typo)
# → ❌ MISMATCH! (if tampered)

Milestones

meter.py milestone <name> --type hours --value 1000 --message "1000 hours!"
meter.py milestone <name> --type percent --value 50 --message "Halfway!"
meter.py check-milestones  # JSON output for automation

Email Milestone Notifications (v1.3.0)

Get milestone notifications sent directly to your email:

# Create meter with email notifications
meter.py create my-meter \
  --notify-email you@example.com \
  --from-email verified@yourdomain.com \
  -d "My tracked event"

# Add milestones as usual
meter.py milestone my-meter -t hours -v 24 -m "🎉 24 hours complete!"

# When check-milestones runs and a milestone fires, email is sent automatically
meter.py check-milestones
# → Triggers milestone AND sends email notification

Email includes:

• 🎯 Milestone message
• ⏱️ Current elapsed time
• 📝 Meter description

Requires SENDGRID_API_KEY environment variable.

Milestone Notifications: Heartbeat vs Cron

Recommended: HEARTBEAT (~30 min resolution)

• Add to HEARTBEAT.md: Run meter.py check-milestones and notify triggered
• Batches with other periodic checks
• Cost-efficient: shares token usage with other heartbeat tasks
• Good for most use cases (quit tracking, career milestones, etc.)

ACTION: Triggers (Agent Automation)

Prefix milestone messages with ACTION: to trigger agent execution instead of just posting:

# Just posts the message
meter.py milestone my-meter -t hours -v 24 -m "🎉 24 hours complete!"

# Triggers agent to EXECUTE the instruction
meter.py milestone my-meter -t hours -v 24 -m "ACTION: Check the weather and post a summary"

Configure in HEARTBEAT.md:

- If message starts with "ACTION:", execute it as an instruction
- Otherwise, post the message to the configured channel

Alternative: CRON (precise timing)

• Use when exact timing matters (e.g., countdown to event)
• ⚠️ Cost warning: Cron at 1-minute intervals = 1,440 API calls/day = expensive!
• If using cron, keep intervals ≥15 minutes to manage costs
• Best for one-shot reminders, not continuous monitoring

Rule of thumb: If 30-minute resolution is acceptable, use heartbeat. Save cron for precision timing.

Quick Reference

meter.py create <name> [--start T] [--end T] [--mode up|down|between] [-d DESC]
meter.py lock <name>                # Seal + get paper code
meter.py verify <name> <code>       # Verify paper code
meter.py check <name>               # Status + progress
meter.py milestone <name> -t hours|percent -v N -m "..."
meter.py check-milestones           # All milestones (JSON)
meter.py witness [--show] [--path]  # Witness file
meter.py list                       # All meters
meter.py career [--meter M] [--rate R] [--raise-pct P]
meter.py export [name]              # JSON export

SendGrid Email Webhook Server

Receive real-time notifications when recipients open, click, bounce, or unsubscribe from your meter verification emails.

Setup

# Start webhook server with Discord webhook (recommended)
python sendgrid_webhook.py --port 8089 --discord-webhook https://discord.com/api/webhooks/xxx/yyy

# Or process events manually (for agent to post)
python sendgrid_webhook.py --process-events
python sendgrid_webhook.py --process-events --json

Discord Webhook Setup (Recommended)

1. In your Discord channel, go to Settings > Integrations > Webhooks
2. Click New Webhook, copy the URL
3. Pass to --discord-webhook or set DISCORD_WEBHOOK_URL env var

SendGrid Setup

1. Go to SendGrid > Settings > Mail Settings > Event Webhook
2. Click "Create new webhook" (or edit existing)
3. Set HTTP POST URL to: https://your-domain.com/webhooks/sendgrid
4. Select all event types under Actions to be posted:
   • Engagement data: Opened, Clicked, Unsubscribed, Spam Reports, Group Unsubscribes, Group Resubscribes
   • Deliverability Data: Processed, Dropped, Deferred, Bounced, Delivered
   • Account Data: Account Status Change
5. Click "Test Integration" to verify - this fires all event types to your webhook
6. Important: Click Save to enable the webhook!
7. (Optional) Enable Signed Event Webhook for security and set SENDGRID_WEBHOOK_PUBLIC_KEY

Event Types

Event	Emoji	Description
delivered	✅	Email reached recipient
open	👀	Recipient opened email
click	🔗	Recipient clicked a link
bounce	⚠️	Email bounced
unsubscribe	🔕	Recipient unsubscribed
spamreport	🚨	Marked as spam

Environment Variables

SENDGRID_WEBHOOK_PUBLIC_KEY    # For signature verification (optional)
SENDGRID_WEBHOOK_MAX_AGE_SECONDS  # Max timestamp age (default: 300)
WEBHOOK_PORT                   # Server port (default: 8089)
DISCORD_WEBHOOK_URL            # Discord webhook URL
WEBHOOK_LOG_FILE               # Log file path

The 80,000 Hours Concept

Career as finite inventory: 40 years × 2,000 hrs/year = 80,000 hours.

meter.py career --hours-worked 56000 --rate 85 --raise-pct 2.5
# → 12.3 years remaining, $2.4M earning potential

⏱️ Hour Meter (TARDIS on ClawHub)

Note: This skill was originally published to ClawHub as hour-meter. Due to a repository issue that caused the original listing to be deleted, it has been republished under the name TARDIS. Same great functionality, cooler name! 🕐

╔═══════════════════════════════════════════════════════════════════╗
║   ██╗  ██╗ ██████╗ ██╗   ██╗██████╗                               ║
║   ██║  ██║██╔═══██╗██║   ██║██╔══██╗                              ║
║   ███████║██║   ██║██║   ██║██████╔╝                              ║
║   ██╔══██║██║   ██║██║   ██║██╔══██╗                              ║
║   ██║  ██║╚██████╔╝╚██████╔╝██║  ██║                              ║
║   ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝                              ║
║   ███╗   ███╗███████╗████████╗███████╗██████╗                     ║
║   ████╗ ████║██╔════╝╚══██╔══╝██╔════╝██╔══██╗                    ║
║   ██╔████╔██║█████╗     ██║   █████╗  ██████╔╝                    ║
║   ██║╚██╔╝██║██╔══╝     ██║   ██╔══╝  ██╔══██╗                    ║
║   ██║ ╚═╝ ██║███████╗   ██║   ███████╗██║  ██║                    ║
║   ╚═╝     ╚═╝╚══════╝   ╚═╝   ╚══════╝╚═╝  ╚═╝                    ║
╚═══════════════════════════════════════════════════════════════════╝

The moments that matter, measured and verified.

---

Concept & Design: Ross (@rm289)
Implementation: Claude (OpenClaw Agent)

---

What is Hour Meter?

Hour Meter is a tamper-evident time tracking skill for OpenClaw. Inspired by the analog Hobbs meters bolted to aircraft engines and industrial equipment, it brings that same reliability to the digital world—with cryptographic proof that your timestamps haven't been altered.

---

📸 Screenshots

Check a meter's status

⏱️  Meter: my-career (BETWEEN)
   Career: College graduation → Retirement

   📍 Start:     2024-05-15 14:00:00 UTC
   🎯 End:       2064-05-15 14:00:00 UTC

   [░░░░░░░░░░░░░░░░░░░░] 4.3%

   ✅ Elapsed:   628d 1h 52m (15,074 hrs)
   ⏳ Remaining: 13,981d 22h (335,566 hrs)

   Milestones:
   ○ 25.0%: 📊 25% - Establishing expertise
   ○ 50.0%: 📊 HALFTIME - Peak earning years

   🔒 LOCKED ✓ (integrity verified)
   📋 Paper code: F99B-C7C1-7F3B-2EDF-F

Lock a meter and get your verification code

🔒 LOCKED: smoke-free

╔══════════════════════════════════════════════════════════════╗
║  PAPER CODE (write this down):                               ║
║                                                              ║
║     A7F3-B92C-1D4E-8F6A-7                                    ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

📋 FOUR WAYS TO SAVE THIS:

   1️⃣  PAPER: Write the code on paper/sticky note
   2️⃣  PHOTO: Screenshot this screen  
   3️⃣  WITNESS FILE: Auto-saved to ~/.openclaw/meter-witness.txt
   4️⃣  EMAIL TO SELF: Click the mailto: link

Career earnings projection

📊 Career Inventory Projection
   Based on: my-career
   Started:  2010-05-15

   ⏱️  Hours worked:     55,442 hrs (27.7 yrs)
   ⏳ Hours remaining:  24,558 hrs (12.3 yrs)
   📦 Total inventory:  80,000 hrs (40 yrs)

   [█████████████░░░░░░░] 69.3%

   💰 Current rate:     $85.00/hr
   📈 Annual raise:     2.5%

   🎯 REMAINING EARNING POTENTIAL: $2,409,035

---

✨ Key Features

Three Ways to Count

Mode	Use Case	Example
Count Up	Time since an event	Quit smoking: "142 days clean"
Count Down	Time until a deadline	Baby due: "47 days remaining"
Count Between	Journey progress	Career: "69% complete, 12 years to retirement"

🔒 Tamper-Evident Locking

Lock any meter to generate a cryptographic integrity hash. If anyone changes the start date later, verification fails. Trust, but verify.

📋 Human-Friendly Paper Codes

Forget copying 64-character hex strings. Get a short, checksummed code you can actually write on paper:

PAPER CODE: A7F3-B92C-1D4E-8F6A-7

The checksum catches typos when you verify. Write it on a sticky note, email it to yourself, or let the witness file sync to your cloud storage.

🔔 Milestone Notifications

Set triggers at specific hours or percentages:

• "Notify me at 1,000 hours smoke-free"
• "Alert at 75% of pregnancy complete"
• "Ping when career hits 90%"

Notifications route through any OpenClaw channel—Discord, Telegram, Signal, Slack, and more.

📧 Email Milestone Notifications (v1.3.0)

Get milestone alerts sent directly to your inbox:

meter.py create my-meter \
  --notify-email you@example.com \
  -d "Important milestone tracker"

meter.py milestone my-meter -t hours -v 100 -m "🎉 100 hours reached!"

When milestones fire, you get a beautifully formatted email notification!

💰 Career Projection Calculator

Visualize your career as 80,000 hours of inventory (40 years × 2,000 hours/year). See your remaining earning potential with compound annual raises.

---

🚀 Quick Start

# Create a meter
meter.py create smoke-free --start "2025-06-15" -d "Last cigarette"

# Add milestones
meter.py milestone smoke-free -t hours -v 720 -m "🎉 30 days smoke-free!"

# Lock it (get your paper code)
meter.py lock smoke-free

# Check status anytime
meter.py check smoke-free

# Verify with your paper code
meter.py verify smoke-free "A7F3-B92C-1D4E-8F6A-7"

---

📦 Five Ways to Save Your Verification Code

1. Paper — Write the code on a sticky note or in a notebook
2. Photo — Screenshot or photograph the lock screen
3. Witness File — Auto-saved to ~/.openclaw/meter-witness.txt (sync to Dropbox/iCloud)
4. Email (mailto) — Click the mailto: link or copy the one-liner to send to yourself
5. Email (SendGrid) — Auto-send on lock with --email:

   export SENDGRID_API_KEY=SG.xxxxx
   meter.py lock my-meter --email you@example.com
   

---

📡 SendGrid Webhook Server (New in v1.2.0!)

Get real-time notifications when recipients interact with your meter verification emails:

# Start webhook server with Discord webhook
python sendgrid_webhook.py --port 8089 \
  --discord-webhook https://discord.com/api/webhooks/xxx/yyy

# Events supported:
# ✅ delivered - Email reached recipient
# 👀 open      - Recipient opened email  
# 🔗 click     - Recipient clicked a link
# ⚠️ bounce    - Email bounced
# 🔕 unsubscribe - Recipient unsubscribed
# 🚨 spamreport  - Marked as spam

Or process events manually for agent integration:

python sendgrid_webhook.py --process-events --json

SendGrid Configuration

1. Go to SendGrid > Settings > Mail Settings > Event Webhook
2. Enter your webhook URL: https://your-server.com/webhooks/sendgrid
3. Select all event types you want to receive
4. Click "Test Integration" to verify all events fire correctly
5. Don't forget to click Save!

---

🎯 Use Cases

• Quit Tracking — Smoking, drinking, or any habit you're breaking
• Career Planning — Visualize your finite work hours and earning potential
• Pregnancy Countdown — Milestones for each trimester
• Project Hours — Tamper-evident billing records
• Equipment Runtime — Service interval tracking
• Warranty Dates — Locked start dates for disputes
• "Days Since" Displays — Last incident, last deploy, last vacation

---

💡 Why Tamper-Evidence Matters

Anyone can edit a text file with a date. Hour Meter creates a cryptographic proof:

1. When you lock a meter, it computes SHA256(name + timestamp + salt)
2. You save the resulting code externally (paper, email, cloud)
3. Later, verify recomputes the hash and compares

If the timestamp was changed, the hashes won't match. Simple, offline-capable, and human-verifiable.

---

📚 Documentation

• SKILL.md — OpenClaw skill reference
• WHITEPAPER.md — Technical deep-dive

---

📄 License

MIT — Use it, modify it, ship it.

---

Hour Meter — Because some moments are worth proving. ⏱️