Home

Awesome

<p align="center"> <img src="https://ik.imagekit.io/turnupdev/focus-new-logo_Sy07sN3gG.png" width="300" height="300" alt="Focus logo"> </p> <p align="center"> <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt=""></a> <a href="https://github.com/ayoisaiah/focus/actions"><img src="https://github.com/ayoisaiah/focus/actions/workflows/test.yml/badge.svg" alt="Github Actions"></a> <a href="https://golang.org"><img src="https://img.shields.io/badge/Made%20with-Go-1f425f.svg" alt="made-with-Go"></a> <a href="https://goreportcard.com/report/github.com/ayoisaiah/focus"><img src="https://goreportcard.com/badge/github.com/ayoisaiah/focus" alt="GoReportCard"></a> <a href="https://github.com/ayoisaiah/focus"><img src="https://img.shields.io/github/go-mod/go-version/ayoisaiah/focus.svg" alt="Go.mod version"></a> <a href="https://github.com/ayoisaiah/focus/blob/master/LICENCE"><img src="https://img.shields.io/github/license/ayoisaiah/focus.svg" alt="LICENCE"></a> <a href="https://github.com/ayoisaiah/focus/releases/"><img src="https://img.shields.io/github/release/ayoisaiah/focus.svg" alt="Latest release"></a> </p> <h1 align="center">Focus on your task</h1>

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.

๐Ÿ… How it works

  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 minute break.

โœจ Main features

๐Ÿ’ป Screenshots

Focus first run

Focus statistics

Focus

โšก Installation

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

๐Ÿ“ฆ NPM Package

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.

๐Ÿš€ Usage

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

focus

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

โš™ Configuration

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.

โณ Sessions

Focus has 3 types of sessions: work, short break, and long break.

๐Ÿ’ผ Work sessions

๐Ÿ˜Ž Break sessions

Tagging sessions

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

Focus notification

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.

๐Ÿ”Š Ambient sounds

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:

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'

๐Ÿ“ˆ Statistics & History

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'

๐Ÿ“ƒ Listing sessions

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:

โœ’ Editing sessions

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

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

๐Ÿค Contribute

Bug reports and feature requests are much welcome! Please open an issue before creating a pull request.

โš– Licence

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