Skip to main content

A simple countdown timer to boost effectiveness.

Project description



Timebox is a simple yet effective tool for staying efficient during a workday.

Timeboxing is a time management technique that is believed to boost productivity by limiting the time during which a task is supposed to be completed. A time box is a fixed period of time alloted for a task or activity. The period of time to spend on the task is decided first (default 45 minutes). The duration of a time box may depend on the task or activity. Alternatively, the task may be scoped in a manner that it can be completed in a fixed size time box. Then a timer is started with the decided time interval. Once the timer notifies that the time interval has expired, any activity or work on the task is stopped, and a short break is taken before beginning another time box.

Timebox is inspired by susam/timebox

Getting Started

Install timebox by running the following command

pip install simple-timebox

Start a timbeox session with the default config by running


Get a full list of all available parameters by running

timebox --help

Usage: timebox [OPTIONS]

  -t, --time INTEGER              Duration of the time box in minutes
                                  [default: 45]
  -b, --beeps INTEGER             Numbers of beeps to notify that the session
                                  is finished  [default: 3]
  -be, --before_end INTEGER       Notify with an alert X minutes before the
                                  session ends.  [default: 15]
  -bis, --beeps_in_session INTEGER
                                  Number of beeps to notify you that there is
                                  X minutes left of session  [default: 1]
  --alert-midway / --no-alert-midway
  --help                          Show this message and exit.

Set a custom time box session length

timebox --time 30


This is free and open source software. You can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of it, under the terms of the MIT License. See for details.

This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND, express or implied. See for details.


To report bugs, suggest improvements, or ask questions, please create a new issue at

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for simple-timebox, version 0.1.post1
Filename, size File type Python version Upload date Hashes
Filename, size simple_timebox-0.1.post1-py3-none-any.whl (6.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size simple-timebox-0.1.post1.tar.gz (4.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page