Skip to main content
Pomo is configured using a pomo.yaml file in YAML format. This page documents every configuration option, its type, default value, and behavior.

​
Configuration file location

Pomo searches for pomo.yaml in the following order:
  1. Current working directory (./pomo.yaml)
  2. ~/.config/pomo/pomo.yaml (Linux and macOS)
  3. User config directory on other platforms
If no configuration file is found, Pomo uses the default values documented below.

​
Complete example

pomo.yaml
onSessionEnd: ask

asciiArt:
  enabled: true
  font: mono12
  color: "#FF6B6B"

work:
  duration: 25m
  title: "work session"
  notification:
    enabled: true
    urgent: false
    title: "work finished 🎉"
    message: "time to take a break!"
    icon: ""

break:
  duration: 5m
  title: "break session"
  notification:
    enabled: true
    urgent: false
    title: "break over 😴"
    message: "back to work!"
    icon: ""

longBreak:
  enabled: true
  after: 4
  duration: 15m

​
Session behavior

​
onSessionEnd
string
default:"ask"
Controls what happens when a session (work or break) completes.Valid values:
  • ask - Show confirmation dialog asking if you want to start the next session
  • start - Automatically start the next session without prompting
  • quit - Exit Pomo when session completes
Example:
onSessionEnd: start  # Automatically chain sessions
Note: Even with start, you can still use keybindings to control the timer during the session.

​
ASCII art configuration

Controls the large ASCII art timer display.
​
asciiArt.enabled
boolean
default:"true"
Enable or disable the ASCII art countdown timer.When true, displays a large ASCII art timer. When false, shows a simpler text-based timer.Example:
asciiArt:
  enabled: false  # Use minimal text display
​
asciiArt.font
string
default:"mono12"
The ASCII art font to use for the timer display.Valid values:
  • mono12 - Clean monospaced font with rounded edges (default)
  • rebel - Bold angular font with gradient shading
  • ansi - Compact solid block font
  • ansiShadow - Elegant font with box-drawing borders
Example:
asciiArt:
  font: rebel  # Use bold angular font
See the ASCII fonts reference for visual examples of each font.
​
asciiArt.color
string
default:"#FF6B6B"
Hex color code for the ASCII art timer.Must be a valid hex color in the format #RRGGBB.Example:
asciiArt:
  color: "#00FF00"  # Bright green timer
Note: Requires a terminal with true color support for accurate color rendering.

​
Work session configuration

Settings for Pomodoro work sessions.
​
work.duration
duration
default:"25m"
Default duration for work sessions.Uses Go duration format: 25m, 1h30m, 45m, etc.Example:
work:
  duration: 45m  # 45-minute work sessions
Note: Can be overridden per-session using command-line arguments: pomo 1h
​
work.title
string
default:"work session"
Display title shown during work sessions.Appears in the terminal UI and can be used to customize the session label.Example:
work:
  title: "focus time"
​
work.notification.enabled
boolean
default:"true"
Enable desktop notifications when work sessions complete.Example:
work:
  notification:
    enabled: false  # Disable work completion notifications
​
work.notification.urgent
boolean
default:"false"
Mark work completion notifications as urgent.When true, the notification may bypass Do Not Disturb settings (platform-dependent).Example:
work:
  notification:
    urgent: true  # Make notifications more prominent
​
work.notification.title
string
default:"work finished 🎉"
Title text for work completion notifications.Example:
work:
  notification:
    title: "Session complete!"
​
work.notification.message
string
default:"time to take a break!"
Body text for work completion notifications.Example:
work:
  notification:
    message: "Great work! Time to rest."
​
work.notification.icon
string
default:""
Path to custom notification icon image.Supports absolute paths and ~/ for home directory. Leave empty to use the default Pomo icon.Example:
work:
  notification:
    icon: "~/Pictures/work-icon.png"
Note: Icon format support varies by platform (PNG recommended).
​
work.then
array
default:"[]"
Commands to execute when work session completes.Each item is an array of strings representing a command and its arguments.Example:
work:
  then:
    - ["notify-send", "Break time!"]
    - ["play", "~/sounds/break.mp3"]
Security note: Commands run with your user permissions. Only use trusted commands.

​
Break session configuration

Settings for short break sessions between work periods.
​
break.duration
duration
default:"5m"
Default duration for short break sessions.Uses Go duration format: 5m, 10m, 15m, etc.Example:
break:
  duration: 10m  # 10-minute breaks
Note: Can be overridden per-session using: pomo 25m 10m
​
break.title
string
default:"break session"
Display title shown during break sessions.Example:
break:
  title: "rest time"
​
break.notification.enabled
boolean
default:"true"
Enable desktop notifications when break sessions complete.Example:
break:
  notification:
    enabled: true
​
break.notification.urgent
boolean
default:"false"
Mark break completion notifications as urgent.Example:
break:
  notification:
    urgent: false
​
break.notification.title
string
default:"break over 😴"
Title text for break completion notifications.Example:
break:
  notification:
    title: "Break finished!"
​
break.notification.message
string
default:"back to work!"
Body text for break completion notifications.Example:
break:
  notification:
    message: "Ready to focus again?"
​
break.notification.icon
string
default:""
Path to custom notification icon for breaks.Example:
break:
  notification:
    icon: "~/Pictures/break-icon.png"
​
break.then
array
default:"[]"
Commands to execute when break session completes.Example:
break:
  then:
    - ["osascript", "-e", 'say "Back to work"']

​
Long break configuration

Settings for extended break sessions after multiple work periods.
​
longBreak.enabled
boolean
default:"true"
Enable automatic long breaks after a certain number of work sessions.When enabled, Pomo will substitute a long break for a short break every N work sessions.Example:
longBreak:
  enabled: true
​
longBreak.after
integer
default:"4"
Number of work sessions before triggering a long break.After this many completed work sessions, the next break will use longBreak.duration instead of break.duration.Example:
longBreak:
  after: 3  # Long break every 3 work sessions
Validation: Must be greater than 0. Invalid values default to 4.
​
longBreak.duration
duration
default:"15m"
Duration for long break sessions.Typically longer than regular breaks to provide extended rest periods.Example:
longBreak:
  duration: 30m  # 30-minute long breaks

​
Data types reference

​
Duration format

All duration fields use Go’s time.Duration format:
  • s - seconds: 30s, 90s
  • m - minutes: 5m, 25m, 45m
  • h - hours: 1h, 2h
  • Combined: 1h30m, 2h15m30s
Valid examples: 
duration: 25m       # 25 minutes
duration: 1h30m     # 1.5 hours
duration: 90s       # 90 seconds
Invalid examples: 
duration: 25        # Missing unit
duration: 1.5h      # Decimal not allowed
duration: 25min     # Wrong unit name

​
Color format

Color fields accept hex color codes: Format: #RRGGBB where RR, GG, BB are hexadecimal values (00-FF) Examples: 
color: "#FF6B6B"    # Coral red (default)
color: "#00FF00"    # Bright green
color: "#3498DB"    # Blue
color: "#FFFFFF"    # White

​
Configuration validation

Pomo validates configuration values at startup:
  1. Duration parsing: Invalid durations cause an error and prevent startup
  2. Long break count: Values ≤ 0 are reset to default (4)
  3. Font names: Invalid fonts fall back to mono12
  4. File paths: Tilde (~) is expanded to home directory
If Pomo fails to load your configuration file, it will print an error message and exit with code 1. Check the error message for details about what went wrong.

​
Minimal configuration

You don’t need to specify every option. This minimal config is valid:
pomo.yaml
work:
  duration: 25m

break:
  duration: 5m
All other options will use their default values.

​
Platform-specific notes

​
macOS

  • Notifications use native macOS notification center
  • Config location: ~/.config/pomo/pomo.yaml
  • Icon format: PNG, ICNS

​
Linux

  • Notifications use libnotify (requires notify-send)
  • Config location: ~/.config/pomo/pomo.yaml
  • Icon format: PNG, SVG

​
Windows

  • Notifications use Windows notification system
  • Config location: %APPDATA%\pomo\pomo.yaml
  • Icon format: PNG, ICO

​
Implementation reference

Configuration is implemented in:
  • Config loading: config/config.go:113-143
  • Default values: config/config.go:66-98
  • Validation: config/config.go:137-140
  • Struct definitions: config/config.go:26-59

Build docs developers (and LLMs) love

Get started for freeTalk to us