# Timer

> Runs background timers and alarms, notifying the user when they complete.

- Skill: `kbarbel640-del/timer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kbarbel640-del/timer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kbarbel640-del/timer/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity, Coding & Dev Tools, Task Management
- Tags: Alarm, Background Process, Node, Reminder, Timer
- Author: kbarbel640-del (https://skillmd.com/u/kbarbel640-del)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/kbarbel640-del/timer

---


# 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

```bash
# 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
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
bash background:true command:"node {baseDir}/timer.js 2m 'Take a break'"
```

### Pomodoro Session
```bash
# 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
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

```bash
# 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)