Repository files navigation

Focus is a cross-platform productivity timer for the command line. It is basedon thePomodoro Technique, atime management method developed by Francesco Cirillo in the late 1980s.

1. Pick a task you need to accomplish.
2. Set a timer for 25 minutes and start working without interruptions.
3. When the timer rings, take a short break for 5 minutes.
4. Once you've completed four work sessions, you can take a longer 15 minutebreak.

• 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 throughgo install (requires Go1.16 or later):

go install github.com/ayoisaiah/focus/cmd/focus@latest

On Linux, thelibasound2-dev package is required to compile Focus. Ubuntu orDebian users can install it through the command below:

sudo apt install libasound2-dev

You can also install Focus through itsNPM package:

Withnpm:

npm i @ayoisaiah/focus -g

Withyarn:

yarn global add @ayoisaiah/focus

Other installation methods areavailable here.

Once Focus is installed, run it using the command below:

focus

Note: Only one instance offocus can be active at a time.

When you run Focus for the first time, it will prompt you to set your preferredtimer lengths, and how many sessions before a long break. Afterwards, you maychange these values by using command-line options or editing theconfig.ymlfile which will be located in~/.config/focus/ on Linux,%LOCALAPPDATA%\focus on Windows, and~/Library/Application Support/focus onmacOS.

Here's the default configuration settings:

work_mins:25# work session lengthwork_msg:Focus on your task# work session message (shown in terminal and notification)short_break_mins:5# short break session lengthshort_break_msg:Take a breather# short break session message (shown in terminal and notification)long_break_mins:15# long break session lengthlong_break_msg:Take a long break# long break session message (shown in terminal and notification)long_break_interval:4# number of sessions before long breaknotify:true# show desktop notificationsauto_start_work:false# Automatically start the next work sessionauto_start_break:true# Automatically start the next break session24hr_clock:false# Show time in 24 hour formatsound:''# name of ambient sound to playsound_on_break:false# play ambient sound during break sessionsdark_theme:true# use colours befitting a dark backgroundsession_cmd:''# execute an arbitrary command after each session

If you specify a command-line argument while running focus, it will override thecorresponding 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 changethe length, or changework_mins in theconfig.yml file.
• Message displayed in the terminal and desktop notification can be changedusingwork_msg.
• You can pause a work session by pressingCtrl-C. Usefocus resume tocontinue from where you stopped.
• Thefocus resume command supports the--sound,--sound-on-break, and--disable-notification flags.
• Ifauto_start_work isfalse, you will be prompted to start each worksession manually. Otherwise if set totrue, it will start without yourintervention.
• 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 worksessions 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 tochange the length, or setshort_break_mins in theconfig.yml file.
• Long break is 15 minutes by default. Use the--long-break or-l option tochange the length, or setlong_break_mins in theconfig.yml file.
• Message displayed in the terminal and desktop notification can be changedusingshort_break_msg andlong_break_msg.
• PressingCtrl-C during a break session will interrupt it. Runfocus resumeto skip to the next work session.
• Ifauto_start_break isfalse, you will be prompted to start each breaksession manually. Otherwise if set totrue, it will start without yourintervention.

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. Setnotify tofalse in your configfile, or use the--disable-notification flag if you don't want notificationsonce a session ends.

Focus provides six ambient sounds by default:coffee_shop,playground,wind,rain,summer_night, andfireplace. You can play a sound using the--sound option, or set a default sound in your config file through thesoundkey.

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 thesound 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 pausedduring break sessions, and resumed again in the next work session. If you'd liketo retain the ambient sound during a break session, set thesound_on_breakconfig option totrue, or use the--sound-on-break or-sob flag.

You can also disable sounds when starting or resuming a session by setting--sound tooff:

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 howlong you focused for overall. It also displays a break down by week, and hour tolet you know what times you tend to be productive.

You can change the reporting period through the--period or-p option. Itaccepts 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 ofacceptable formats in theproject 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 thelist command to display a table of your work sessions instead ofaggregated statistics. Use the--period or--start and--end option tochange 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 away that a graceful shutdown was not possible.

You can edit the tags of one or more sessions through theedit-tag command. Itaccepts the same options as thelist command to select the sessions to beedited. The tags are command-line arguments. You will be prompted before theupdate is carried out.

The command below edits the tags of all sessions recordedtoday and taggedwithwriting. It updates the tags for each session to writing, novel, andonce-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 aslist except thatdelete is usedinstead. 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 beforecreating a pull request.

Created by Ayooluwa Isaiah, and released under the terms of theMIT Licence.