Skip to main content

​
Config file locations

Pomo searches for its configuration file in the following order:
  1. Current directory: pomo.yaml (highest priority)
  2. System config directory:
    • Linux/macOS: ~/.config/pomo/pomo.yaml
    • Windows: %APPDATA%\pomo\pomo.yaml
  3. Built-in defaults if no config file is found
Pomo will use built-in default values if no config file is found. You can run Pomo without any configuration.

​
Configuration structure

The pomo.yaml file uses YAML format to configure sessions, notifications, visual appearance, and post-session commands.

​
Complete example

pomo.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/Bahaaio/pomo/main/config/schema.json
# pomo config file
# https://github.com/Bahaaio/pomo

onSessionEnd: ask

asciiArt:
  enabled: true
  font: mono12
  color: "#5A56E0"

work:
  duration: 25m
  title: work session
  notification:
    enabled: true
    urgent: false
    title: work finished 🎉
    message: time to take a break
    icon: ~/path/to/icon.png
  then:
    - [spd-say, "Time to take a break"]

break:
  duration: 5m
  title: break session
  notification:
    enabled: true
    urgent: false
    title: break over 😴
    message: back to work!
    icon: ~/path/to/icon.png
  then:
    - [spd-say, "Back to work!"]

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

​
Session end behavior

The onSessionEnd setting controls what happens when a session completes.
​
onSessionEnd
string
default:"ask"
Action to take after session completionOptions:
  • ask - Prompt user to start next session (default)
  • start - Automatically start the next session
  • quit - Exit the application

​
Examples

onSessionEnd: ask
Use ask for maximum control, start for uninterrupted Pomodoro cycles, or quit if you only want to run single sessions.

​
Config file validation

Pomo includes a JSON schema for config file validation. Add this line at the top of your pomo.yaml for editor autocompletion: 
# yaml-language-server: $schema=https://raw.githubusercontent.com/Bahaaio/pomo/main/config/schema.json
This enables YAML language server features like autocompletion and validation in editors like VS Code.

​
Next steps

Session settings

Configure work, break, and long break durations

ASCII art

Customize timer fonts and colors

Notifications

Set up desktop notifications

Commands

Run custom commands after sessions

Build docs developers (and LLMs) love

Get started for freeTalk to us