Pomodoro Timer Skill

Overview

A 25-minute timer for focused work sessions that saves every session to SQLite. Enables history tracking, productivity analytics, and pattern recognition over time.

This is a System Skill - it provides handles to operate a personal data system. As commands run and sessions accumulate, context builds and compounds. The system learns patterns and provides increasingly valuable insights through an OODA loop of observation, orientation, decision, and action.

Mental Model: The OODA Loop

Operating this skill involves running a continuous cycle:

1. Observe → Check current status (./pomodoro status) and review history (./pomodoro history)
2. Orient → Analyze patterns in the data (./pomodoro stats --period week)
3. Decide → Determine optimal actions (e.g., "Morning sessions have 95% completion - schedule deep work then")
4. Act → Start sessions (./pomodoro start), provide recommendations, celebrate milestones

Each cycle builds on accumulated data, making insights more valuable over time.

Dependencies

• Binary location: ~/.claude/skills/pomodoro/pomodoro
• Database: Auto-created at ~/.claude/skills/pomodoro/pomodoro.db on first run
• No external dependencies required

Quick Decision Tree

User task → What kind of request?
   ├─ Start focused work → Check status first, then start session
   ├─ Check current timer → Use status command
   ├─ Review productivity → Use stats command (day/week/month/year)
   ├─ View past sessions → Use history command
   └─ Stop early → Use stop command

Core Commands

To see all available options: Run ./pomodoro --help or ./pomodoro <command> --help

Starting a Session

Begin a Pomodoro session:

# Traditional 25-minute Pomodoro
./pomodoro start --task "Refactor authentication module"

# Custom durations and cycles
./pomodoro start --task "Quick review" --work 5 --break 3 --cycles 2
./pomodoro start --task "Deep focus" --work 50 --br...