Focus is a cross-platform productivity timer for the command line. It is based on the Pomodoro Technique, a time management method developed by Francesco Cirillo in the late 1980s.
- Pick a task you need to accomplish.
- Set a timer for 25 minutes and start working without interruptions.
- When the timer rings, take a short break for 5 minutes.
- Once you've completed four work sessions, you can take a longer 15 minute break.
- Work and break session lengths are customisable.
- You can pause and resume work sessions.
- You can skip break sessions.
- You can customise the number of sessions before a long break.
- You can set a maximum number of sessions.
- Desktop notifications are supported on all platforms.
- You can customise the notification messages.
- Detailed statistics for your work history are provided including charts.
- Focus provides six built-in ambient sounds that you can play during a session, and you can add your own custom sounds.
Focus is written in Go, so you can install it through go install
(requires Go
1.16 or later):
$ go install github.com/ayoisaiah/focus/cmd/focus@latest
On Linux, the libasound2-dev
package is required to compile Focus. Ubuntu or
Debian users can install it through the command below:
$ sudo apt install libasound2-dev
You can also install Focus through its NPM package:
With npm
:
$ npm i @ayoisaiah/focus -g
With yarn
:
$ yarn global add @ayoisaiah/focus
Other installation methods are available here.
Once Focus is installed, run it using the command below:
$ focus
Note: Only one instance of focus
can be active at a time.
When you run Focus for the first time, it will prompt you to set your preferred
timer lengths, and how many sessions before a long break. Afterwards, you may
change these values by using command-line options or editing the config.yml
file which will be located in ~/.config/focus/
on Linux,
%LOCALAPPDATA%\focus
on Windows, and ~/Library/Application Support/focus
on
macOS.
Here's the default configuration settings:
work_mins: 25 # work session length
work_msg: Focus on your task # work session message (shown in terminal and notification)
short_break_mins: 5 # short break session length
short_break_msg: Take a breather # short break session message (shown in terminal and notification)
long_break_mins: 15 # long break session length
long_break_msg: Take a long break # long break session message (shown in terminal and notification)
long_break_interval: 4 # number of sessions before long break
notify: true # show desktop notifications
auto_start_work: false # Automatically start the next work session
auto_start_break: true # Automatically start the next break session
24hr_clock: false # Show time in 24 hour format
sound: '' # name of ambient sound to play
sound_on_break: false # play ambient sound during break sessions
dark_theme: true # use colours befitting a dark background
session_cmd: '' # execute an arbitrary command after each session
If you specify a command-line argument while running focus, it will override the corresponding value in the config file.
Focus has 3 types of sessions: work, short break, and long break.
- Set to 25 minutes length by default. Use the
--work
or-w
option to change the length, or changework_mins
in theconfig.yml
file. - Message displayed in the terminal and desktop notification can be changed
using
work_msg
. - You can pause a work session by pressing
Ctrl-C
. Usefocus resume
to continue from where you stopped. - The
focus resume
command supports the--sound
,--sound-on-break
, and--disable-notification
flags. - If
auto_start_work
isfalse
, you will be prompted to start each work session manually. Otherwise if set totrue
, it will start without your intervention. - The maximum number of work sessions can be set using the
--max-sessions
or-max
option. After that number is reached, focus will exit. - Use the
--long-break-interval
or-int
option to set the number of work sessions before a long break, or changelong_break_interval
in yourconfig.yml
.
- Short break is 5 minutes by default. Use the
--short-break
or-s
option to change the length, or setshort_break_mins
in theconfig.yml
file. - Long break is 15 minutes by default. Use the
--long-break
or-l
option to change the length, or setlong_break_mins
in theconfig.yml
file. - Message displayed in the terminal and desktop notification can be changed
using
short_break_msg
andlong_break_msg
. - Pressing
Ctrl-C
during a break session will interrupt it. Runfocus resume
to skip to the next work session. - If
auto_start_break
isfalse
, you will be prompted to start each break session manually. Otherwise if set totrue
, it will start without your intervention.
You can use the --tag
or -t
flag to apply a tag to a new session:
focus --tag 'side-project'
Multiple tags are supported (use commas to separate each):
focus --tag 'side-project,focus'
Notifications are turned on by default. Set notify
to false
in your config
file, or use the --disable-notification
flag if you don't want notifications
once a session ends.
Focus provides six ambient sounds by default: coffee_shop
, playground
,
wind
, rain
, summer_night
, and fireplace
. You can play a sound using the
--sound
option, or set a default sound in your config file through the sound
key.
focus --sound 'coffee_shop'
If you want to play a custom sound instead, copy the file (supports MP3, FLAC, OGG, and WAV) to the appropriate directory for your operating system:
- Linux:
~/.local/share/focus/static
- Windows:
%LOCALAPPDATA\focus\static
- macOS:
~/Library/Application Support/focus/static
Afterwards, specify the name of the file in the sound
key or --sound
option.
Note that custom sounds must include the file extension.
focus --sound 'university.mp3'
focus --sound 'subway.ogg'
focus --sound 'airplane.wav'
focus --sound 'stadium_noise.flac'
By default, ambient sounds are played only during work sessions. They are paused
during break sessions, and resumed again in the next work session. If you'd like
to retain the ambient sound during a break session, set the sound_on_break
config option to true
, or use the --sound-on-break
or -sob
flag.
You can also disable sounds when starting or resuming a session by setting
--sound
to off
:
focus --sound 'off'
focus resume --sound 'off'
focus stats
The above command will display your work history for the last 7 days by default. You'll see how many work sessions you completed, how many you abandoned, and how long you focused for overall. It also displays a break down by week, and hour to let you know what times you tend to be productive.
You can change the reporting period through the --period
or -p
option. It
accepts the following values: today, yesterday, 7days, 14days, 30days,
90days, 180days, 365days, all-time.
focus stats -p 'today'
focus stats -p 'all-time'
You can also set a specific time period using the --start
and --end
options.
The latter defaults to the current day if not specified. See the list of
acceptable formats in the
project wiki.
focus stats --start '2021-08-06'
focus stats --start '2021-08-06' --end '2021-08-07'
focus stats --start '2021-07-23 12:00:05 PM' --end '2021-07-29 03:25:00 AM'
Use the list
command to display a table of your work sessions instead of
aggregated statistics. Use the --period
or --start
and --end
option to
change the reporting period (defaults to the last 7 days).
focus list
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| # | START DATE | END DATE | TAGGED | STATUS |
| 1 | Feb 21, 2023 09:09 PM | Feb 21, 2023 09:09 PM | | abandoned |
| 2 | Feb 21, 2023 09:11 PM | Feb 21, 2023 09:11 PM | | abandoned |
| 3 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:15 PM | reading | abandoned |
| 4 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:16 PM | side-project | completed |
| 5 | Feb 21, 2023 09:16 PM | Feb 21, 2023 09:17 PM | writing | completed |
| 6 | Feb 21, 2023 09:21 PM | Feb 21, 2023 09:22 PM | writing | completed |
| 7 | Feb 21, 2023 09:22 PM | Feb 21, 2023 09:23 PM | writing | completed |
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
You can filter the list by tag:
focus list --tag 'client,piano'
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| # | START DATE | END DATE | TAGGED | STATUS |
| 1 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:15 PM | reading | abandoned |
| 2 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:16 PM | side-project | completed |
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Note:
- Sessions that cross over to a new day will count towards that day's sessions.
- A session with an empty end date indicates that the process was ended such a way that a graceful shutdown was not possible.
You can edit the tags of one or more sessions through the edit-tag
command. It
accepts the same options as the list
command to select the sessions to be
edited. The tags are command-line arguments. You will be prompted before the
update is carried out.
The command below edits the tags of all sessions recorded today
and tagged
with writing
. It updates the tags for each session to writing, novel, and
once-upon-a-time
.
focus edit-tag --tag 'writing' -p 'today' 'writing' 'novel' 'once-upon-a-time'
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| # | START DATE | END DATE | TAGGED | STATUS |
| 1 | Feb 21, 2023 09:16 PM | Feb 21, 2023 09:17 PM | writing ยท novel ยท once-upon-a-time | completed |
| 2 | Feb 21, 2023 09:21 PM | Feb 21, 2023 09:22 PM | writing ยท novel ยท once-upon-a-time | completed |
| 3 | Feb 21, 2023 09:22 PM | Feb 21, 2023 09:23 PM | writing ยท novel ยท once-upon-a-time | completed |
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
WARNING The sessions above will be updated. Press ENTER to proceed
Deleting sessions is done in the same way as list
except that delete
is used
instead. You will be prompted to confirm the deletion before it is carried out.
focus delete --start '2023-02-21 21:21:00'
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| # | START DATE | END DATE | TAGGED | STATUS |
| 1 | Feb 21, 2023 09:22 PM | Feb 21, 2023 09:23 PM | writing | completed |
| 2 | Feb 21, 2023 09:33 PM | Feb 21, 2023 09:33 PM | | abandoned |
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
WARNING The above sessions will be deleted permanently. Press ENTER to proceed
Bug reports and feature requests are much welcome! Please open an issue before creating a pull request.
Created by Ayooluwa Isaiah, and released under the terms of the MIT Licence.