Skip to main content
Break sessions help you recharge between focused work periods. While pomo automatically schedules breaks after work sessions, you can also start manual breaks.

​
Starting a break session

Start a break session with the default duration (5 minutes): 
pomo break

​
Custom break duration

Specify a custom break duration: 
pomo break 10m      # 10 minute break
pomo break 15m      # 15 minute break
pomo break 30m      # 30 minute break
Break durations use the same format as work sessions: 5m, 1h, 1h30m, etc.

​
When to use manual breaks

Manual break sessions are useful when:
  • You need a break outside the normal Pomodoro cycle
  • You want to time a specific activity (coffee, walk, lunch)
  • You’re returning from an interruption and want to track the time
  • You’re using pomo for time tracking without strict work/break cycles
If you’re following the Pomodoro cycle, let pomo automatically transition to breaks after work sessions. This maintains your long break counter and cycle tracking.

​
Break types

Pomo supports two types of breaks in the Pomodoro cycle:

​
Short breaks

Short breaks occur after each work session:
config/pomo.yaml
break:
  duration: 5m
  title: break session
Default short breaks are 5 minutes and help you reset between focused work periods.

​
Long breaks

Long breaks occur after a configured number of work sessions:
config/pomo.yaml
longBreak:
  enabled: true
  after: 4          # After 4 work sessions
  duration: 15m
1

Complete work sessions

Finish 4 work sessions (configurable via after)
2

Long break triggered

Pomo automatically offers a long break instead of short break
3

Cycle resets

After the long break, the counter resets and starts tracking toward the next long break
Manually starting a break with pomo break does not count toward the Pomodoro cycle. It’s tracked separately from automatic breaks that follow work sessions.

​
Break session controls

Break sessions support the same keyboard shortcuts as work sessions:
KeyActionDescription
↑ / kAdd timeIncrease break time by 1 minute
SpacePause/ResumePause or resume the timer
← / hResetReset timer to initial duration
sSkipSkip break and return to work
q / Ctrl+CQuitExit the timer

​
Desktop notifications

Configure notifications for when breaks complete:
config/pomo.yaml
break:
  notification:
    enabled: true
    urgent: false
    title: break over 😴
    message: back to work!
    icon: ~/my/icon.png

​
Running commands on completion

Execute custom commands when breaks end:
config/pomo.yaml
break:
  then:
    - [spd-say, "Back to work!"]          # Linux TTS
    # - [say, "Back to work!"]             # macOS TTS
    # - [powershell, Add-Type, ...]        # Windows
Commands run with a 5 second timeout and are automatically cancelled if you start another session.

​
Break session completion

When a break completes, pomo follows the same onSessionEnd behavior as work sessions:
Prompt you to start the next work session:
config/pomo.yaml
onSessionEnd: "ask"

​
Examples

​
Quick coffee break

pomo break 10m
Time a 10-minute coffee break.

​
Lunch break

pomo break 1h
Time a 1-hour lunch break.

​
Extended rest

pomo break 30m
Take a longer 30-minute break after an intense work session.

​
Statistics tracking

All break sessions are tracked in your statistics:
  • Total break duration (all-time)
  • Break time in duration ratio
  • Break sessions are stored in the database with type break
This helps you understand your work/break balance over time.

Work sessions

Learn about starting work sessions

Statistics

View your work and break statistics

Build docs developers (and LLMs) love

Get started for freeTalk to us