Skip to main content
Pomo allows you to play custom sounds when work or break sessions complete using the then field in your configuration. This is useful for audio feedback in addition to or instead of desktop notifications.

​
How it works

The then field accepts an array of commands that run automatically when a session ends. Each command is specified as an array of strings, where the first element is the executable and subsequent elements are arguments. 
work:
  then:
    - [paplay, ~/sounds/work-done.mp3]
Commands in the then field run in parallel with desktop notifications and have a 5-second timeout (defined in actions/actions.go:15).

​
Platform-specific examples

Different operating systems use different audio players. Here are the recommended commands for each platform: 
work:
  duration: 25m
  then:
    - [paplay, ~/sounds/work-done.mp3]

break:
  duration: 5m
  then:
    - [paplay, ~/sounds/break-done.mp3]

​
Text-to-speech examples

You can also use text-to-speech commands for spoken notifications: 
work:
  then:
    - [spd-say, "Time to take a break"]

break:
  then:
    - [spd-say, "Back to work!"]

​
Complete configuration example

Here’s a full example combining sound notifications with desktop notifications: 
work:
  duration: 25m
  title: work session
  
  # Desktop notification
  notification:
    enabled: true
    urgent: true
    title: work finished 🎉
    message: time to take a break
  
  # Sound notification
  then:
    - [paplay, ~/sounds/bell.wav]

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

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

​
Command timeout behavior

All commands in the then field have a 5-second timeout. If a command takes longer than this, it will be terminated.
The timeout is enforced by the context system in actions/actions.go:69. This prevents hung processes from blocking the application.

​
Auto-cancellation

Commands are automatically cancelled when you start the next session. This is handled through Go’s context cancellation mechanism:
1

Session completes

The timer reaches zero and post-actions are triggered
2

Commands start

All commands in the then array begin executing in parallel
3

User starts next session

If you start the next session before commands finish, they receive a cancellation signal
4

Cleanup

Running commands are gracefully terminated

​
Troubleshooting

Check the audio player is installed:
# Linux - check for paplay
which paplay

# macOS - check for afplay
which afplay
Verify the audio file path:
  • Use absolute paths or ~/ for home directory
  • Ensure the file exists and is a valid audio format
  • Test the command manually in your terminal first
Check file permissions:
ls -l ~/sounds/work-done.mp3
If your audio file is longer than 5 seconds, it will be cut off. Solutions:
  • Use shorter audio files (under 5 seconds)
  • The timeout is hardcoded in actions/actions.go:15 and cannot be configured
Common mistakes:
# ❌ Wrong - single string
then: "paplay ~/sounds/bell.wav"

# ❌ Wrong - nested incorrectly
then:
  - paplay ~/sounds/bell.wav

# ✅ Correct - array of arrays
then:
  - [paplay, ~/sounds/bell.wav]

Build docs developers (and LLMs) love

Get started for freeTalk to us