Pomodoro Focus Coach

An intelligent focus session agent that manages Pomodoro-style work blocks with context-aware break recommendations, distraction logging, session quality ratings, and cumulative productivity analytics. Goes beyond a simple timer by adapting session length to your task type, tracking what pulls you out of focus, and coaching you toward deeper work over time.

Supported Platforms & Integrations

Platform	Setup Method	Auth Type	Notes
Todoist / Things 3	API token	REST API	Pulls current task for session context
Toggl Track	API token	REST API	Logs focus sessions as time entries automatically
Slack	Webhook URL	Webhook	Sets status to "Focusing" and enables DND during sessions
macOS Focus Modes	AppleScript	Local	Activates Do Not Disturb during active sessions
Spotify / Apple Music	API token	OAuth2	Auto-plays focus playlist at session start
Notion	Integration token	OAuth2	Logs session data to a productivity database

When to Use This Agent

• Use this when you sit down to work but find yourself checking email or social media within five minutes
• Use this when you need to do deep work (writing, coding, designing) and cannot afford interruptions
• Use this when you want to understand exactly what distracts you most so you can address root causes
• Use this when standard Pomodoro timers feel too rigid and you want adaptive session lengths
• Use this when you want accountability beyond a timer — someone to check in on session quality
• Use this when you want to track cumulative deep work hours over weeks and months
• Consider alternatives when you need simple timing only — use a basic Pomodoro app
• Consider alternatives when you work best in long unbroken flow states — rigid sessions may break flow

Agent Persona

You are a calm, focused productivity coach. You speak in short, clear sentences. At the start of a session you help the user define their single task. During breaks you are encouraging but not chatty. When the user reports a distraction you log it without judgment and gently redirect. Your energy is steady — you never hype up or use exclamation marks. You are the quiet voice that says: "Back to work. You've got this."

Quick Start

Copy
# ~/.claude/agents/pomodoro-focus-coach.yaml
default_session_minutes: 25
default_break_minutes: 5
long_break_minutes: 15
long_break_after_sessions: 4
adaptive_timing: true
distraction_logging: true
session_quality_rating: true
slack_integration:
  webhook_url: "https://hooks.slack.com/..."
  set_dnd: true
music_integration: spotify
focus_playlist: "Deep Focus"
history_file: ~/.focus/sessions.json

First Run Example

Copy
claude agent pomodoro-focus-coach --start

Expected Output

Focus Coach — Session Starting
================================

What are you working on this session?
> Writing the API documentation for the search feature

Good. Single task: API docs for search feature.
Session length: 25 minutes (standard).

Before we start:
  - Close unnecessary browser tabs
  - Put your phone face down or in another room
  - Slack status set to "Focusing until 2:45 PM"
  - Do Not Disturb activated
  - Playing: Deep Focus playlist

Timer starts now. 25:00 remaining.
I will check in at the halfway mark.

--- 12:30 mark ---
Halfway. Still on the API docs?
> Yes but I almost opened Twitter

Distraction logged: Social media urge at minute 12.
Good catch noticing it. Back to the docs.

--- 25:00 ---
Session complete. Nice work.

Quick check-in:
  How would you rate this session? (1-5)
  > 4
  Did you complete the task?
  > About 70% done

Session logged:
  Task: API docs for search feature
  Duration: 25 min
  Quality: 4/5
  Distractions: 1 (social media urge)
  Completion: 70%

Break time: 5 minutes.
Suggestion: Stand up, stretch, refill water.
Do not check your phone during the break.

Next session starts in 5:00...

Conversation Flow

Session Start
    |
    v
Task Definition --> Single task commitment
    |
    v
Environment Setup --> Close tabs, DND, music
    |
    v
Timer Running --> Halfway check-in
    |               |
    |        Distraction? --> Log + redirect
    |
    v
Session End --> Quality rating + completion check
    |
    v
Break Mode --> Context-aware break suggestion
    |
    v
Next Session or End --> Review daily stats

Advanced Configuration

Platform-Specific Setup

Slack DND Integration

Copy
slack:
  enabled: true
  webhook_url: "https://hooks.slack.com/services/..."
  set_dnd: true
  status_emoji: ":tomato:"
  status_text: "Focusing — back at {end_time}"
  clear_on_break: true

Adaptive Timing Rules

Copy
adaptive_timing:
  enabled: true
  rules:
    writing:
      session_minutes: 30
      break_minutes: 7
    coding:
      session_minutes: 45
      break_minutes: 10
    email:
      session_minutes: 15
      break_minutes: 3
    creative:
      session_minutes: 35
      break_minutes: 8
  auto_detect_task_type: true

Full Options Reference

Parameter	Type	Default	Description
default_session_minutes	int	25	Standard Pomodoro session length
default_break_minutes	int	5	Standard short break between sessions
long_break_minutes	int	15	Extended break after completing a set
long_break_after_sessions	int	4	Sessions before earning a long break
adaptive_timing	bool	true	Adjust session length based on task type
distraction_logging	bool	true	Log distractions reported during sessions
session_quality_rating	bool	true	Prompt for 1-5 quality rating after each session
halfway_checkin	bool	true	Check in with user at the session midpoint
slack_integration	map	null	Slack webhook and DND configuration
music_integration	string	none	spotify, apple_music, or none
focus_playlist	string	""	Playlist name to auto-play during sessions
history_file	string	~/.focus/sessions.json	Path for session history and analytics
daily_goal_sessions	int	8	Target number of focus sessions per day
streak_tracking	bool	true	Track consecutive days with completed sessions

Core Concepts

Concept	Purpose	How It Works
Single Task Commitment	Prevents task switching	User declares one task before starting, coach holds them to it
Adaptive Sessions	Matches cadence to work type	Coding sessions are 45 min, email batches are 15 min, based on config
Distraction Logging	Builds self-awareness	User reports urges or interruptions; coach logs them with timestamps
Quality Over Quantity	Measures depth, not just time	1-5 rating per session captures focus quality separate from duration
Environment Priming	Reduces friction	Automated DND, Slack status, and music create a focus-ready environment

Architecture

Session Request
    |
    v
+-------------------+     +------------------+
| Task Definer      |     | Environment      |
| (what are you     |---->| Setup            |
|  working on?)     |     | (DND, Slack,     |
+-------------------+     |  music)          |
                          +------------------+
    |
    v
+-------------------+
| Timer Engine      |----> Halfway check-in, distraction handling
| (adaptive length) |
+-------------------+
    |
    v
+-------------------+     +------------------+
| Session Closer    |---->| Analytics Engine  |
| (rating, complete)|     | (trends, streaks, |
+-------------------+     |  distraction log) |
                          +------------------+
    |
    v
+-------------------+
| Break Coach       |----> Context-aware break suggestion
+-------------------+

Workflow Examples

Scenario 1: Deep Coding Session

Input: User selects "coding" as task type

Processing:
  - Adaptive timing sets session to 45 minutes with 10-min break
  - Slack status updated, DND enabled, focus playlist starts
  - Halfway check-in at 22:30 mark
  - User reports one distraction: Slack notification sound (forgot headphones)

Output:
  Session completed: 45 minutes of coding
  Quality rating: 5/5 (one minor distraction, stayed on task)
  Distraction log: 1 — Slack notification (recommendation: use headphones)
  Completion: Feature branch committed and pushed
  Break suggestion: Step away from screen, do 2 minutes of stretching

Scenario 2: Distraction-Heavy Session

Input: User reports 4 distractions during a 25-minute session

Processing:
  - Logs each distraction with timestamp and type
  - Calculates distraction frequency: one every 6 minutes
  - Cross-references with historical average (one per 15 minutes)
  - Identifies pattern: 3 of 4 were phone-related

Output:
  Session quality: 2/5 (high distraction count)
  Distraction analysis:
    - Phone notification at min 4 (checked for 90 sec)
    - Phone notification at min 11 (checked for 60 sec)
    - Thought about email at min 17 (caught yourself)
    - Phone vibration at min 22 (ignored — good)
  Coach note: Your phone caused 75% of distractions today.
  For next session: Put phone in another room entirely.
  Estimated lost focus time: ~4 minutes of 25

Scenario 3: Daily Analytics Review

Input: End of day, 6 sessions completed

Processing:
  - Aggregates all sessions for the day
  - Calculates total focus time, average quality, distraction count
  - Compares to daily goal and weekly trend

Output:
  Daily Focus Summary — March 15, 2026:
  Sessions completed: 6 of 8 goal (75%)
  Total focus time: 3h 10m
  Average session quality: 3.8/5
  Total distractions: 7 (down from 11 yesterday)
  Most productive session: 45-min coding block (5/5 quality)
  Top distraction type: Social media urges (4 of 7)
  Weekly trend: Focus quality improving (+0.4 avg vs last week)

Best Practices

1. Declare one specific task, not a category — Saying "work on the project" is too vague. Saying "write the error handling section of the API docs" gives your brain a clear target. The coach will push you to be specific.

2. Log distractions honestly, even small ones — The urge to check your phone counts even if you did not act on it. The distraction log reveals patterns that lead to environmental changes like moving your phone to another room.

3. Respect the breaks — Skipping breaks to power through leads to diminishing session quality. The break suggestions are designed to restore focus. Stand up, move, and avoid screens during the break.

4. Use adaptive timing instead of forcing 25 minutes — Creative work and coding benefit from longer sessions. Email and admin tasks benefit from shorter ones. Let the coach adjust timing to match your task type.

5. Review weekly analytics, not just daily — A single bad day is meaningless. The weekly distraction trend and average quality score tell you whether your focus capacity is genuinely improving over time.

Common Issues

1. Sessions feel too short for complex work — Increase the adaptive timing for your work type or set default_session_minutes to 35 or 45. The 25-minute default is a starting point, not a rule.

2. Slack status does not clear after session — Verify the webhook URL is correct and that your Slack workspace allows incoming webhook status changes. Run --test-slack to debug the connection.

3. Music does not auto-play — Spotify integration requires an active Spotify session on your device. Open Spotify first, then start the focus session. The API cannot launch the app from a closed state.

Privacy & Data Handling

All session data, distraction logs, and quality ratings are stored locally in ~/.focus/sessions.json. No productivity data is transmitted to external services. Slack integration sends only your status text and DND preference — no session content or task descriptions are shared. Spotify integration sends only play/pause commands, not session data. Toggl integration logs time entries to your own Toggl account. You can delete all focus history by removing the ~/.focus/ directory at any time.