Timer
Set timers that run in the background. When they complete, you will receive a system notification and MUST respond with the reminder to notify the user.
Quick Start
# Set a 5-minute timer
bash background:true command:"node {baseDir}/timer.js 5m"
Set a timer with a label
bash background:true command:"node {baseDir}/timer.js 10m 'Check the oven'"
Set a timer in seconds
bash background:true command:"node {baseDir}/timer.js 30s"
Set a timer in hours
bash background:true command:"node {baseDir}/timer.js 1h"
Time Formats
| Format | Description | Example |
|---|
Ns
| N seconds | 30s
, 90s
|
Nm
| N minutes | 5m
, 15m
|
Nh
| N hours | 1h
, 2h
|
N
| N minutes (default) | 5
= 5 minutes |
MM:SS
| Minutes and seconds | 5:30
|
HH:MM:SS
| Hours, minutes, seconds | 1:30:00
|
⚠️ CRITICAL: Timer Completion Notification
When a timer completes, you receive a
System:
message like:
System: [2026-01-24 21:27:13] Exec completed (swift-me, code 0) :: ⏰ Timer complete! Check the pasta!
❌ WRONG - Do NOT respond like this:
HEARTBEAT_OK
🎉 Your timer is complete! Check the pasta!
This response will be filtered and NOT delivered to the user!
✅ CORRECT - Respond like this:
⏰ Timer Alert! Your timer is complete: Check the pasta!
Start directly with the notification message. Do NOT include HEARTBEAT_OK.
Why? Responses starting with
HEARTBEAT_OK
followed by less than 300 characters are automatically suppressed and never reach the user. Your timer notification will be lost!
Examples
Cooking Timer
bash background:true command:"node {baseDir}/timer.js 12m 'Pasta is ready!'"
When complete, respond: "⏰ Your 12-minute timer is up! Pasta is ready!"
Quick Reminder
bash background:true command:"node {baseDir}/timer.js 2m 'Take a break'"
Pomodoro Session
# Work session
bash background:true command:"node {baseDir}/timer.js 25m 'Pomodoro done - time for a break!'"
# After user is notified...
# Break
bash background:true command:"node {baseDir}/timer.js 5m 'Break over - back to work!'"
Multiple Timers
bash background:true command:"node {baseDir}/timer.js 5m 'Tea is ready'"
bash background:true command:"node {baseDir}/timer.js 10m 'Eggs are done'"
bash background:true command:"node {baseDir}/timer.js 30m 'Meeting starts soon'"
Managing Timers
# List all running timers
process action:list
Check specific timer status
process action:poll sessionId:XXX
View timer output
process action:log sessionId:XXX
Cancel a timer
process action:kill sessionId:XXX
Notes
- Timers run as background processes with unique sessionIds
- Completed timers exit with code 0
- Cancelled timers (via kill) exit with code 130
- Sound notification plays on macOS when timer completes (if
afplay
available)
- Progress is logged every second (short timers) or every 10 seconds (long timers)
