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.
Thyme on GitHub


# Mac
$ brew install hughbien/tap/thyme

# Linux
$ wget -O thyme
$ chmod +x thyme

# Source (requires Crystal)
$ git clone
$ cd thyme
$ make
$ make install

For Mac, use Homebrew: brew install hughbien/tap/thyme

For Linux, download the latest binary: thyme-linux-amd64. MD5 checksum is 221d80b1fb7ec32ac58ca193852d9afb.

To compile from source, you'll need Crystal installed first. Then checkout the repository and run make && make install.


$ 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 to 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