Skip to main content

​
The then field

The then field allows you to run custom commands when work or break sessions complete. This is useful for playing sounds, triggering scripts, or integrating with other tools.
​
then
array
List of commands to run after session completionEach command is specified as an array: [command, arg1, arg2, ...]

​
Basic syntax

pomo.yaml
work:
  duration: 25m
  then:
    - [command, arg1, arg2]
    - [another-command, arg]

break:
  duration: 5m
  then:
    - [command, arg]
Commands are specified as arrays, not strings. Use [spd-say, "Hello"] instead of "spd-say Hello".

​
Command execution behavior

​
Timeout

All commands run with a 5-second timeout. If a command takes longer than 5 seconds, it will be terminated.
Source: actions/actions.go:15
var CommandTimeout = 5 * time.Second
Commands that take longer than 5 seconds will be killed. Use background processes or scripts for long-running tasks.

​
Auto-cancellation

Commands are automatically cancelled when you start the next session. This prevents sound notifications or scripts from running after you’ve moved on.
If you skip to the next session or start a new one before commands complete, they will be cancelled automatically.

​
Execution order

Multiple commands in the then array run sequentially in the order specified:
pomo.yaml
work:
  then:
    - [echo, "Work done"]      # Runs first
    - [spd-say, "Take a break"] # Runs second
    - [notify-send, "Break time!"] # Runs third

​
Sound notifications

Play sounds when sessions complete using platform-specific audio commands.
Use paplay (PulseAudio) or spd-say (speech dispatcher):
work:
  then:
    - [paplay, ~/sounds/work-done.mp3]

break:
  then:
    - [paplay, ~/sounds/break-over.mp3]
Or use text-to-speech:
work:
  then:
    - [spd-say, "Time to take a break"]

break:
  then:
    - [spd-say, "Back to work!"]
Use afplay (built-in audio player) or say (text-to-speech):
work:
  then:
    - [afplay, ~/sounds/work-done.mp3]

break:
  then:
    - [afplay, ~/sounds/break-over.mp3]
Or use text-to-speech:
work:
  then:
    - [say, "Time for a break"]

break:
  then:
    - [say, "Back to work"]
Use PowerShell to play sounds:
work:
  then:
    - [powershell, start, work-done.mp3]

break:
  then:
    - [powershell, start, break-over.mp3]
Or use Windows speech:
work:
  then:
    - [powershell, "Add-Type -AssemblyName System.Speech; (New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak('Time for a break')"]

​
Example configurations

work:
  duration: 25m
  then:
    - [spd-say, "Time to take a break"]

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

​
Custom scripts

Run custom scripts when sessions complete:
pomo.yaml
work:
  then:
    - [/home/user/scripts/work-done.sh]

break:
  then:
    - [/home/user/scripts/break-over.sh]

​
Example script

work-done.sh
#!/bin/bash

# Play a sound
paplay ~/sounds/bell.mp3

# Send a notification
notify-send "Work Session Complete" "Time for a break!"

# Log to file
echo "$(date): Work session completed" >> ~/pomo.log

# Post to webhook (optional)
curl -X POST https://your-webhook.com/work-done
Make the script executable:
Terminal
chmod +x ~/scripts/work-done.sh
Scripts must complete within 5 seconds or they will be terminated. For longer tasks, use background processes (&) or nohup.

​
Integration examples

Send a Slack message when sessions complete:
work:
  then:
    - [curl, -X, POST, -H, "Content-Type: application/json", -d, '{"text":"Work session complete!"}', https://hooks.slack.com/services/YOUR/WEBHOOK/URL]
Or use a script:
notify-slack.sh
#!/bin/bash
curl -X POST -H 'Content-Type: application/json' \
  -d '{"text":"Work session complete!"}' \
  https://hooks.slack.com/services/YOUR/WEBHOOK/URL
Control smart lights or devices:
work:
  then:
    - [curl, -X, POST, http://192.168.1.100/api/lights/1/on]

break:
  then:
    - [curl, -X, POST, http://192.168.1.100/api/lights/1/dim]
Log session completion:
log-session.sh
#!/bin/bash
echo "$(date '+%Y-%m-%d %H:%M:%S'): $1 session completed" >> ~/pomo-log.txt

work:
  then:
    - [/home/user/scripts/log-session.sh, work]

break:
  then:
    - [/home/user/scripts/log-session.sh, break]
Perform system actions:
work:
  then:
    # Increase screen brightness
    - [brightnessctl, set, 100%]

break:
  then:
    # Dim screen brightness
    - [brightnessctl, set, 50%]

​
Error handling

If a command fails, Pomo logs the error but continues execution: 
failed to run command '["spd-say" "Hello"]': exit status 1
Command failures don’t stop Pomo. Check terminal logs if commands aren’t working as expected.

​
Debugging commands

Test commands manually before adding them to your config:
Terminal
# Test text-to-speech
spd-say "Time to take a break"

# Test audio playback
paplay ~/sounds/bell.mp3

# Test script execution
/home/user/scripts/work-done.sh
Run commands in your terminal first to ensure they work before adding them to pomo.yaml.

​
Best practices

  1. Keep commands short - Remember the 5-second timeout
  2. Use absolute paths - Avoid relying on $PATH or relative paths
  3. Test commands first - Run them manually before adding to config
  4. Use scripts for complex tasks - Move multi-step logic to separate scripts
  5. Handle errors gracefully - Commands may fail; don’t rely on them completing
  6. Use background processes - For tasks that should continue after Pomo starts the next session
Avoid commands that require user input or interaction. They will block until the 5-second timeout.

Build docs developers (and LLMs) love

Get started for freeTalk to us