Find Me On

My Homepage





RSS Feeds

My Stuff

Shared Items

Search This Blog


Josh Braun’s Blog // I have it written down somewhere . . .

Simple Command Line Pomodoro Timer Jul 10, 2014

I’ve found Francesco Cirillo’s Pomodoro Technique to be a useful way of organizing my work and getting stuff done.  It involves breaking up your work into four 25-minute intervals (“pomodori”), separated by five-minute breaks.  At the end of the four work intervals, you allow yourself a longer break (usually 15 or 30 minutes) before repeating the whole process.

The alternation of predetermined work and break intervals improves my focus—the 25-minute work intervals are long enough to get real tasks done, and I can avoid succumbing to the usual distractions like checking my email or perusing various web-based time sinks when I know I have a break coming up.

Cirillo apparently suggests it’s important to make a list of tasks beforehand and says the ritual of setting a physical timer that ticks insistently at you as you work improves your focus.  But like many folks, I use a watered down version of the technique that forgoes the to-do list and makes use of a digital timer.

There are tons of little pomodoro timer apps, websites, and software programs out there to keep time for you.  Still, since I do a lot of work on the command line and appreciate its relatively distraction-free aesthetic, I wanted a command-line based pomodoro timer.  So I wrote a quick one in PHP and I’m sharing it.


To use it, you first need PHP installed on your system.  On Mac OSX, PHP is preinstalled, so there’s no need to do anything at this stage.  On other *nix systems, it’s simple to get PHP via your distribution’s package manager. Windows users using a Cygwin BASH or tcsh shell can also get PHP through Cygwin Ports.

Once you’ve got PHP up and running, download the ‘pomodoro’ file from SourceForge. Place the file in whatever directory you want it to live in, and ‘cd’ to that directory in your terminal application.

Next, make the file executable:

$ chmod +x pomodoro

Now, test the script to see if it works:

$ ./pomodoro

If the timer begins counting down, you’re good to go.  If not, then check the path to PHP given in the file itself to make sure it matches the path to PHP on your own system.  Specifically, in your shell enter the command:

$ whereis php

This will display the path to PHP on your system. Then open the ‘pomodoro’ file in a text editor and change the filepath following the characters ‘#!’ on the first line of the file to match the path given by the ‘whereis’ command.

Optionally, you may wish to add the directory containing the ‘pomodoro’ script to your PATH, which will allow you to start the timer by typing ‘pomodoro’ into your shell from any directory, rather than having to first browse to the directory containing the file, then typing ‘./pomodoro’ with a leading ‘./’.


Be aware of a few command line options I’ve written into the script.  For example, you can manually set the length of the “long break” that follows the four work intervals.  It’s also possible to tell the script to start at a work interval other than the first.  This is useful if  you have to step away for longer than intended during one of the short breaks and want to resume the timer at the next interval, or if you want to use the timer, but don’t have time for a full session of four work periods.

Like most any command line program, you can also pause the script (and hence the countdown) by typing Control-Z, and resume it by entering the command ‘fg’ into the terminal.

Here is the full usage information from the ‘help’ screen, which you can display with the command ‘pomodoro -h’:

Usage: pomodoro [OPTION]... 
`pomodoro' is a simple command line implementation of a pomodoro timer.
More information on the `Pomodoro Technique' developed by Francesco Cirillo can be
found on Wikipedia:

  pomodoro -l=45            # Run the pomodoro timer with a long break of 45 minutes.
  pomodoro -p=2             # Start the pomodoro timer at the second 25-minute interval.
  pomodoro -p=3 -l=15       # Start the pomodoro timer at the third 25-minute interval
                              and make the long break 15 minutes.

Basic usage:
  -h, --help                Display help and usage information
  -l, --length=NUMBER       Set the length of the long break (default is 30 minutes).
  -p, --pomodoro=NUMBER     Specify pomodoro interval at which to start (default is 1).
      --usage               Alias of the `--help' option
  -v, --version             Display version and license information

Each time a work or break countdown ends, the timer will ring the terminal bell, emitting a brief sound or visual cue depending on your terminal application’s settings. Enjoy!

This entry was posted in Technology and tagged , , . Bookmark the permalink.