Thyme Pomodoro Timer

Tmux Integration, Hooks, & Extensions

$ thyme -h
Usage: thyme [options]
Runs a pomodoro timer in your tmux status bar
  -h, --help            print help message
  -f, --foreground      run in foreground instead of daemon
  -r, --repeat [count]  repeat timer with breaks in-between
  -s, --stop            stops current timer

$ thyme
0:bash* 1:vim- 25:00 (1/5)

Thyme is a command line tool that runs a Pomodoro timer in the Tmux status bar.
Latest Release / Thyme on GitHub


$ thyme       # starts timer for 25 minutes
$ thyme       # pauses/unpauses a running timer
$ thyme -s    # stops current timer

$ thyme -f    # runs timer in foreground (not as daemon)
$ thyme -r    # repeat timer indefinitely (with 5 min breaks)
$ thyme -r 5  # repeat timer 5x times

Start a timer with thyme. You'll have 25 minutes by default.

Some other useful options:

  • thyme — run again to pause
  • thyme --stop — to stop/abandon current timer
  • thyme --foreground — don't run as a daemon
  • thyme --repeat — repeat timer indefinitely (with breaks)
  • thyme --repeat 4 — repeat timer four times (with breaks)


# in ~/.thymerc file
timer = 1500               # seconds per pomodoro
timer_break = 300          # seconds per break
timer_warning = 300        # seconds left to show warning
repeat = 4                 # default times to repeat
color_default = "default"  # color for pomodoros
color_warning = "red"      # color for pomodoros warnings
color_break = "default"    # color for breaks
status_align = "left"      # "left" or "right" in tmux

The default Pomodoro is 25 minutes and breaks last for 5 minutes. To configure these, set the timer and timer_break options in your ~/.thymerc file. All times are set as seconds.

You can also specify the default times to repeat (with the -r flag), colors, and tmux status alignment.

With Existing Tmux Status

# in ~/.thymerc file
status_override = false
# in ~/.tmux.conf file
set -g status-right '#(cat ~/.thyme-tmux)'
set -g status-interval 1

Thyme takes over the entire status-right or status-left by default. If you have an existing Tmux status, you can integrate the Thyme timer into it instead.

Set status_override = false in your ~/.thymerc. Thyme outputs the timer to a ~/.thyme-tmux file that your status will need to read from.

Custom Hooks

# in ~/.thymerc file
events = ["after"]
command = """
terminal-notifier -message \"Pomodoro done #{repeat_suffix}\" -title \"thyme\"

events = ["after_break"]
command = """
terminal-notifier -message \"Break done #{repeat_suffix}\" -title \"thyme\"

events = ["after_all"]
command = "echo \"You're all done, congrats!\""

Custom hooks can be added via the [hooks.*] group. Valid events are:

  • before — before a pomodoro
  • after — after a pomodoro
  • before_break — before a break
  • after_break — after a break
  • before_all — before entire session
  • after_all — after entire session

The following placeholders are available for hook commands:

  • #{repeat_index} — current repeat index
  • #{repeat_total} — total repeat count for this session
  • #{repeat_suffix} — if repeating is on, will return (index/total) eg (3/5). Otherwise empty string.

Custom Options

# in ~/.thymerc file
flag = "-t"
flag_long = "--today"
description = "Open TODO today file"
command = "vim ~/path/to/"

flag = "-H"
flag_long = "--hello name"
description = "Say hello!"
command = """
echo \"Hello #{flag}! #{args}.\"
""" # eg `thyme -H John "How are you?"`

Custom options can be added via the [options.*] group. The today example adds a -t option for opening a todo today file. The hello example echos to STDOUT.

The following placeholders are available for option commands:

  • #{flag} — the argument passed to your flag
  • #{args} — any additional arguments passed to the thyme binary