Simple Pomodoro timer for focused work sessions with session tracking and productivity analytics. Use when users request focus timers, ask about productivity patterns, or want to track work sessions over time. Demonstrates the System Skill Pattern (CLI + SKILL.md + Database).
Simple Pomodoro timer for focused work sessions with session tracking and productivity analytics. Use when users request focus timers, ask about productivity patterns, or want to track work sessions over time. Demonstrates the System Skill Pattern (CLI + SKILL.md + Database).
license
MIT
allowed-tools
["Bash","Read"]
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:
Observe → Check current status (./pomodoro status) and review history (./pomodoro history)
Orient → Analyze patterns in the data (./pomodoro stats --period week)
Decide → Determine optimal actions (e.g., "Morning sessions have 95% completion - schedule deep work then")
Act → Start sessions (./pomodoro start), provide recommendations, celebrate milestones
Each cycle builds on accumulated data, making insights more valuable over time.
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
./pomodoro status
./pomodoro status --json # For programmatic use
Output example:
Active session: "Write documentation"
Started: 2:30 PM
Time remaining: 18 minutes
Viewing History
Review past sessions:
./pomodoro history --days 7 # Last 7 days
./pomodoro history --days 30 # Last 30 days
./pomodoro history --json # For programmatic use
Output includes:
Task names
Start and completion times
Duration
Completion status (completed vs. stopped early)
Analyzing Productivity
Get insights from accumulated data:
./pomodoro stats --period day # Today's stats
./pomodoro stats --period week # This week
./pomodoro stats --period month # This month
./pomodoro stats --period year # This year
./pomodoro stats --json # For programmatic use
Statistics include:
Total and completed sessions
Completion rate (% of sessions finished)
Total focus time
Most productive hours of day
Task distribution (which tasks completed most often)
Acknowledge completion rates: "Excellent focus - 90% this week!"
Suggest optimal times based on historical data
Encourage consistent practice
Point out improvements: "Completion rate up from 75% to 85%"
Data Analysis
Review daily stats at end of each day
Check weekly patterns for scheduling insights
Track trends over time (month, year)
Use JSON output for custom analytics
Cross-reference task types with completion rates
Identify peak productive hours
Command Composition
Combine commands for deeper insights:
# Morning check-in: status + daily stats
./pomodoro status
./pomodoro stats --period day
# Weekly review: history + stats
./pomodoro history --days 7 --json
./pomodoro stats --period week --json
# Long-term analysis: monthly trends
./pomodoro stats --period month --json
./pomodoro history --days 90 --json
Technical Notes
JSON Output
All commands support --json flag for programmatic access:
./pomodoro status --json
./pomodoro history --json
./pomodoro stats --json
Use JSON output when:
Parsing data programmatically
Building custom analytics
Feeding into other tools
Need structured output
Database
Location: ~/.claude/skills/pomodoro/pomodoro.db
Format: SQLite database with single sessions table
Persistence: All sessions saved permanently
Growth: Database grows with use (each session ~100 bytes)
Analytics: Richer insights as data accumulates
Maintenance: No cleanup or archiving needed
Schema:
CREATE TABLE sessions (
id INTEGERPRIMARY KEY,
task TEXT NOT NULL,
duration INTEGERNOT NULL,
started_at TEXT NOT NULL,
completed_at TEXT
);
Timer Behavior
Runs in foreground process (blocks terminal)
Shows progress every minute during work sessions
Shows progress every minute during break sessions
Automatically transitions from work → break → work
Each work session saved separately to database
Supports custom durations via flags
Example session flow (3 cycles):
Work 25min → Break 5min → Work 25min → Break 5min → Work 25min → Break 5min → Done
Result: 3 separate database entries (one per work session)
Binary Location
Path: ~/.claude/skills/pomodoro/pomodoro
Always use: ./pomodoro when running from skill directory
Full path: ~/.claude/skills/pomodoro/pomodoro from anywhere
To run from skill directory:
cd ~/.claude/skills/pomodoro
./pomodoro start --task "Task name"
The System Skill Pattern in Action
This skill demonstrates the System Skill Pattern (CLI + SKILL.md + Database):
CLI Binary: Handles to operate the system - start sessions, query history, analyze patterns
SKILL.md: Operating procedure for the OODA loop (Observe → Orient → Decide → Act)
SQLite Database: Persistent memory where every session adds context
The key insight: With these three components, the skill animates a system rather than just responding to requests. Each interaction builds on the last. Analytics become richer. Insights get sharper. The tool compounds in value.
Example of compounding value:
Week 1: "Started 5 sessions"
Week 4: "Morning sessions: 95% completion. Afternoon: 70%. Schedule deep work mornings."
This pattern works for any skill where accumulating data adds value and where giving Claude handles to operate a system creates more utility than one-time responses.
See also: README.md for deeper technical details and implementation guide.
