Pomodoro

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 --break 10 --cycles 1

# Flash cards (rapid cycles)
./pomodoro start --task "Flash cards" --work 2 --break 1 --cycles 5

Options:

• --work <minutes> - Work duration (default: 25)
• --break <minutes> - Break duration (default: 5)
• --cycles <count> - Number of work+break rounds (default: 1)

Behavior:

• Only one session can run at a time
• Timer runs in foreground showing progress every minute
• Breaks start automatically after work sessions
• Next work session starts automatically after break (if cycles remaining)
• Each work session saved separately to database

JSON output example:

./pomodoro start --task "Write docs" --json
# Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}

Checking Status

See if a timer is running:

./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)

JSON output example:

{
  "period": "week",
  "total_sessions": 23,
  "completed": 19,
  "completion_rate": 0.826,
  "focus_hours": 7.9,
  "productive_hours": [9, 10, 11],
  "top_tasks": ["Refactoring", "Documentation", "Code review"]
}

Stopping Early

End the current session before completion:

./pomodoro stop

Use when interruptions occur or task completes early. Session marked as incomplete in database.

Essential Workflows

Starting Focused Work

To help a user start a Pomodoro session:

1. Check for active session: ./pomodoro status
2. If clear, start with appropriate options:
   • Traditional: ./pomodoro start --task "Deep work on authentication"
   • Custom: ./pomodoro start --task "Sprint planning" --work 15 --break 5 --cycles 3
   • Flash cards: ./pomodoro start --task "Vocabulary review" --work 2 --break 1 --cycles 10
3. Confirm to user: "25-minute Pomodoro started for [task name]. Timer running."

Daily Review

To provide daily productivity summary:

1. Fetch today's data: ./pomodoro stats --period day --json
2. Parse and present insights:
   • "Completed 6 Pomodoros today (3.0 hours of focus time)"
   • "5/6 sessions completed - 83% completion rate"
   • "Most work on: Refactoring, Documentation"
   • "Productive hours: 9-11 AM"

Weekly Analysis

To provide weekly productivity review:

1. Fetch week's data: ./pomodoro stats --period week --json
2. Identify patterns:
   • Compare to previous weeks if data available
   • Note peak productive hours
   • Identify which task types have highest completion rates
3. Make recommendations:
   • "Schedule deep work during your peak hours (9-11 AM)"
   • "Coding sessions have 90% completion vs 70% for meetings - consider task segmentation"

Pattern Recognition Over Time

As sessions accumulate, provide increasingly valuable insights:

After a few sessions (1-5):

• "Completed 3 Pomodoros today"
• "Building momentum with focus sessions"

After several days (5-20 sessions):

• "7 completed out of 9 sessions - 78% completion rate"
• "Most productive between 9-11 AM"

After a week (20-50 sessions):

• "Strong week: 23 sessions with 85% completion"
• "Peak productivity: 9-11 AM (95% completion) vs 2-4 PM (65% completion)"
• "Consider scheduling deep work in morning hours"

After a month (50+ sessions):

• "Coding tasks: 90% completion rate"
• "Documentation tasks: 70% completion rate"
• "Consider shorter Pomodoros (15 min) for documentation work"

After several months (100+ sessions):

• "Completion rate improving: 72% → 85% over last 3 months"
• "Wednesday is most productive day (92% completion)"
• "Afternoon sessions improve when limited to 15 minutes"
• "80% more sessions completed on coding vs documentation tasks"

Commands to use for pattern recognition:

./pomodoro stats --period month --json  # Get monthly data
./pomodoro history --days 90 --json     # Review last 90 days

Milestone Celebrations

Acknowledge progress at key milestones:

• 10 sessions: "First 10 Pomodoros complete - building the habit!"
• 50 sessions: "50 sessions milestone - over 20 hours of focused work!"
• 100 sessions: "100 Pomodoros! That's 40+ hours of deep focus time."
• High completion rates: "95% completion this week - excellent focus!"

To check milestone status: ./pomodoro stats --period year --json

Common Pitfalls

Starting When Session Already Active

❌ Don't start a new session without checking status first ✅ Do run ./pomodoro status before starting

Why: Only one session can run at a time. Starting when active causes error.

Pattern to follow:

# Check first
./pomodoro status
# If "No active session", then start
./pomodoro start --task "New task"

Non-Descriptive Task Names

❌ Don't use vague names: "Work", "Stuff", "Things" ✅ Do use specific names: "Refactor auth module", "Write API docs", "Review PR #123"

Why: Descriptive names enable better analytics. Pattern recognition needs specificity to identify which task types work best.

Interrupting Long-Running Sessions

❌ Don't let terminal close or process be killed during session ✅ Do use ./pomodoro stop if interruption is necessary

Why: Interrupted sessions aren't saved to database. Use stop command to record partial session.

Ignoring Completion Rate Signals

❌ Don't ignore consistent low completion rates for certain task types ✅ Do adjust session length based on task type patterns

Why: If documentation tasks show 60% completion vs 90% for coding, shorter sessions (15 min) may work better for documentation.

How to identify:

./pomodoro stats --period month --json
# Review completion rates by task type
# Suggest duration adjustments based on patterns

Best Practices

Session Management

• Use descriptive task names for better analytics
• Complete full 25 minutes when possible
• Take breaks between sessions
• Adjust duration based on task type (use --work flag)
• Stop explicitly if interrupted (don't let process be killed)

User Interaction

• Celebrate milestones (10, 50, 100, 250, 500 sessions)
• 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 INTEGER PRIMARY KEY,
  task TEXT NOT NULL,
  duration INTEGER NOT 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):

1. CLI Binary: Handles to operate the system - start sessions, query history, analyze patterns
2. SKILL.md: Operating procedure for the OODA loop (Observe → Orient → Decide → Act)
3. 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."
• Month 3: "Coding: 90% completion. Docs: 72%. Try 15-minute sessions for documentation."

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.