{"id":14563531,"url":"https://github.com/ayoisaiah/focus","last_synced_at":"2025-08-02T08:45:34.968Z","repository":{"id":38534937,"uuid":"323647448","full_name":"ayoisaiah/focus","owner":"ayoisaiah","description":"A fully featured productivity timer for the command line, based on the Pomodoro Technique. Supports Linux, Windows, and macOS.","archived":false,"fork":false,"pushed_at":"2024-04-14T00:18:32.000Z","size":10806,"stargazers_count":378,"open_issues_count":8,"forks_count":19,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T14:27:16.302Z","etag":null,"topics":["command-line","countdown-timer","pomodoro","pomodoro-timer","productivity","whitenoise"],"latest_commit_sha":null,"homepage":"https://github.com/ayoisaiah/focus","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayoisaiah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"patreon":"freshman"}},"created_at":"2020-12-22T14:22:49.000Z","updated_at":"2024-04-16T01:32:30.211Z","dependencies_parsed_at":"2023-10-14T18:30:51.738Z","dependency_job_id":"6334a06a-3f14-43b3-ba27-3e0609117d5c","html_url":"https://github.com/ayoisaiah/focus","commit_stats":{"total_commits":167,"total_committers":1,"mean_commits":167.0,"dds":0.0,"last_synced_commit":"02cb19c7cdffba71c78bc000c1db2701fa94158c"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisaiah%2Ffocus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisaiah%2Ffocus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisaiah%2Ffocus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisaiah%2Ffocus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayoisaiah","download_url":"https://codeload.github.com/ayoisaiah/focus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":217902372,"owners_count":16248434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","countdown-timer","pomodoro","pomodoro-timer","productivity","whitenoise"],"created_at":"2024-09-07T02:02:02.468Z","updated_at":"2024-09-07T02:07:16.712Z","avatar_url":"https://github.com/ayoisaiah.png","language":"Go","funding_links":["https://patreon.com/freshman"],"categories":["Go","productivity"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n   \u003cimg src=\"https://ik.imagekit.io/turnupdev/focus-new-logo_Sy07sN3gG.png\" width=\"300\" height=\"300\" alt=\"Focus logo\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"http://makeapullrequest.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat\" alt=\"\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/ayoisaiah/focus/actions\"\u003e\u003cimg src=\"https://github.com/ayoisaiah/focus/actions/workflows/test.yml/badge.svg\" alt=\"Github Actions\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://golang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Made%20with-Go-1f425f.svg\" alt=\"made-with-Go\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://goreportcard.com/report/github.com/ayoisaiah/focus\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/ayoisaiah/focus\" alt=\"GoReportCard\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/ayoisaiah/focus\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/ayoisaiah/focus.svg\" alt=\"Go.mod version\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/ayoisaiah/focus/blob/master/LICENCE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/ayoisaiah/focus.svg\" alt=\"LICENCE\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/ayoisaiah/focus/releases/\"\u003e\u003cimg src=\"https://img.shields.io/github/release/ayoisaiah/focus.svg\" alt=\"Latest release\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eFocus on your task\u003c/h1\u003e\n\nFocus is a cross-platform productivity timer for the command line. It is based\non the [Pomodoro Technique](https://en.wikipedia.org/wiki/Pomodoro_Technique), a\ntime management method developed by Francesco Cirillo in the late 1980s.\n\n## 🍅 How it works\n\n1. Pick a task you need to accomplish.\n2. Set a timer for 25 minutes and start working without interruptions.\n3. When the timer rings, take a short break for 5 minutes.\n4. Once you've completed four work sessions, you can take a longer 15 minute\n   break.\n\n## ✨ Main features\n\n- Work and break session lengths are customisable.\n- You can pause and resume work sessions.\n- You can skip break sessions.\n- You can customise the number of sessions before a long break.\n- You can set a maximum number of sessions.\n- Desktop notifications are supported on all platforms.\n- You can customise the notification messages.\n- Detailed statistics for your work history are provided including charts.\n- Focus provides six built-in ambient sounds that you can play during a session,\n  and you can add your own custom sounds.\n\n## 💻 Screenshots\n\n![Focus first run](https://ik.imagekit.io/turnupdev/focus-screenshot_6BU22Sj-J.png)\n\n![Focus statistics](https://ik.imagekit.io/turnupdev/focus-stats-screenshot_0dLtjklu_0.png)\n\n![Focus](https://ik.imagekit.io/turnupdev/focus-ops_bcJ7-Gnuag.png)\n\n## ⚡ Installation\n\nFocus is written in Go, so you can install it through `go install` (requires Go\n1.16 or later):\n\n```bash\ngo install github.com/ayoisaiah/focus/cmd/focus@latest\n```\n\nOn Linux, the `libasound2-dev` package is required to compile Focus. Ubuntu or\nDebian users can install it through the command below:\n\n```bash\nsudo apt install libasound2-dev\n```\n\n### 📦 NPM Package\n\nYou can also install Focus through its\n[NPM package](https://www.npmjs.com/package/@ayoisaiah/focus):\n\nWith `npm`:\n\n```bash\nnpm i @ayoisaiah/focus -g\n```\n\nWith `yarn`:\n\n```bash\nyarn global add @ayoisaiah/focus\n```\n\nOther installation methods are\n[available here](https://github.com/ayoisaiah/focus/wiki/Installation/).\n\n## 🚀 Usage\n\nOnce Focus is installed, run it using the command below:\n\n```\nfocus\n```\n\n**Note:** Only one instance of `focus` can be active at a time.\n\n## ⚙ Configuration\n\nWhen you run Focus for the first time, it will prompt you to set your preferred\ntimer lengths, and how many sessions before a long break. Afterwards, you may\nchange these values by using command-line options or editing the `config.yml`\nfile which will be located in `~/.config/focus/` on Linux,\n`%LOCALAPPDATA%\\focus` on Windows, and `~/Library/Application Support/focus` on\nmacOS.\n\nHere's the default configuration settings:\n\n```yml\nwork_mins: 25 # work session length\n\nwork_msg: Focus on your task # work session message (shown in terminal and notification)\n\nshort_break_mins: 5 # short break session length\n\nshort_break_msg: Take a breather # short break session message (shown in terminal and notification)\n\nlong_break_mins: 15 # long break session length\n\nlong_break_msg: Take a long break # long break session message (shown in terminal and notification)\n\nlong_break_interval: 4 # number of sessions before long break\n\nnotify: true # show desktop notifications\n\nauto_start_work: false # Automatically start the next work session\n\nauto_start_break: true # Automatically start the next break session\n\n24hr_clock: false # Show time in 24 hour format\n\nsound: '' # name of ambient sound to play\n\nsound_on_break: false # play ambient sound during break sessions\n\ndark_theme: true # use colours befitting a dark background\n\nsession_cmd: '' # execute an arbitrary command after each session\n```\n\nIf you specify a command-line argument while running focus, it will override the\ncorresponding value in the config file.\n\n## ⏳ Sessions\n\nFocus has 3 types of sessions: work, short break, and long break.\n\n### 💼 Work sessions\n\n- Set to 25 minutes length by default. Use the `--work` or `-w` option to change\n  the length, or change `work_mins` in the `config.yml` file.\n- Message displayed in the terminal and desktop notification can be changed\n  using `work_msg`.\n- You can pause a work session by pressing `Ctrl-C`. Use `focus resume` to\n  continue from where you stopped.\n- The `focus resume` command supports the `--sound`, `--sound-on-break`, and\n  `--disable-notification` flags.\n- If `auto_start_work` is `false`, you will be prompted to start each work\n  session manually. Otherwise if set to `true`, it will start without your\n  intervention.\n- The maximum number of work sessions can be set using the `--max-sessions` or\n  `-max` option. After that number is reached, focus will exit.\n- Use the `--long-break-interval` or `-int` option to set the number of work\n  sessions before a long break, or change `long_break_interval` in your\n  `config.yml`.\n\n### 😎 Break sessions\n\n- Short break is 5 minutes by default. Use the `--short-break` or `-s` option to\n  change the length, or set`short_break_mins` in the `config.yml` file.\n- Long break is 15 minutes by default. Use the `--long-break` or `-l` option to\n  change the length, or set `long_break_mins` in the `config.yml` file.\n- Message displayed in the terminal and desktop notification can be changed\n  using `short_break_msg` and `long_break_msg`.\n- Pressing `Ctrl-C` during a break session will interrupt it. Run `focus resume`\n  to skip to the next work session.\n- If `auto_start_break` is `false`, you will be prompted to start each break\n  session manually. Otherwise if set to `true`, it will start without your\n  intervention.\n\n## Tagging sessions\n\nYou can use the `--tag` or `-t` flag to apply a tag to a new session:\n\n```bash\nfocus --tag 'side-project'\n```\n\nMultiple tags are supported (use commas to separate each):\n\n```bash\nfocus --tag 'side-project,focus'\n```\n\n## 🔔 Notifications\n\n![Focus notification](https://ik.imagekit.io/turnupdev/focus-notify_igz_8z0Jnp.png)\n\nNotifications are turned on by default. Set `notify` to `false` in your config\nfile, or use the `--disable-notification` flag if you don't want notifications\nonce a session ends.\n\n## 🔊 Ambient sounds\n\nFocus provides six ambient sounds by default: `coffee_shop`, `playground`,\n`wind`, `rain`, `summer_night`, and `fireplace`. You can play a sound using the\n`--sound` option, or set a default sound in your config file through the `sound`\nkey.\n\n```bash\nfocus --sound 'coffee_shop'\n```\n\nIf you want to play a custom sound instead, copy the file (supports MP3, FLAC,\nOGG, and WAV) to the appropriate directory for your operating system:\n\n- **Linux**: `~/.local/share/focus/static`\n- **Windows**: `%LOCALAPPDATA\\focus\\static`\n- **macOS**: `~/Library/Application Support/focus/static`\n\nAfterwards, specify the name of the file in the `sound` key or `--sound` option.\n**Note that custom sounds must include the file extension**.\n\n```bash\nfocus --sound 'university.mp3'\nfocus --sound 'subway.ogg'\nfocus --sound 'airplane.wav'\nfocus --sound 'stadium_noise.flac'\n```\n\nBy default, ambient sounds are played only during work sessions. They are paused\nduring break sessions, and resumed again in the next work session. If you'd like\nto retain the ambient sound during a break session, set the `sound_on_break`\nconfig option to `true`, or use the `--sound-on-break` or `-sob` flag.\n\nYou can also disable sounds when starting or resuming a session by setting\n`--sound` to `off`:\n\n```bash\nfocus --sound 'off'\nfocus resume --sound 'off'\n```\n\n## 📈 Statistics \u0026 History\n\n```bash\nfocus stats\n```\n\nThe above command will display your work history for the last 7 days by default.\nYou'll see how many work sessions you completed, how many you abandoned, and how\nlong you focused for overall. It also displays a break down by week, and hour to\nlet you know what times you tend to be productive.\n\nYou can change the reporting period through the `--period` or `-p` option. It\naccepts the following values: _today_, _yesterday_, _7days_, _14days_, _30days_,\n_90days_, _180days_, _365days_, _all-time_.\n\n```bash\nfocus stats -p 'today'\nfocus stats -p 'all-time'\n```\n\nYou can also set a specific time period using the `--start` and `--end` options.\nThe latter defaults to the current day if not specified. See the list of\nacceptable formats in the\n[project wiki](https://github.com/ayoisaiah/focus/wiki/Acceptable-datetime-formats-for-filtering).\n\n```bash\nfocus stats --start '2021-08-06'\nfocus stats --start '2021-08-06' --end '2021-08-07'\nfocus stats --start '2021-07-23 12:00:05 PM' --end '2021-07-29 03:25:00 AM'\n```\n\n### 📃 Listing sessions\n\nUse the `list` command to display a table of your work sessions instead of\naggregated statistics. Use the `--period` or `--start` and `--end` option to\nchange the reporting period (defaults to the last 7 days).\n\n```bash\nfocus list\n```\n\n```text\n┌──────────────────────────────────────────────────────────────────────────────┐\n| # | START DATE            | END DATE              | TAGGED       | STATUS    |\n| 1 | Feb 21, 2023 09:09 PM | Feb 21, 2023 09:09 PM |              | abandoned |\n| 2 | Feb 21, 2023 09:11 PM | Feb 21, 2023 09:11 PM |              | abandoned |\n| 3 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:15 PM | reading      | abandoned |\n| 4 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:16 PM | side-project | completed |\n| 5 | Feb 21, 2023 09:16 PM | Feb 21, 2023 09:17 PM | writing      | completed |\n| 6 | Feb 21, 2023 09:21 PM | Feb 21, 2023 09:22 PM | writing      | completed |\n| 7 | Feb 21, 2023 09:22 PM | Feb 21, 2023 09:23 PM | writing      | completed |\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\nYou can filter the list by tag:\n\n```bash\nfocus list --tag 'client,piano'\n```\n\n```text\n┌──────────────────────────────────────────────────────────────────────────────┐\n| # | START DATE            | END DATE              | TAGGED       | STATUS    |\n| 1 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:15 PM | reading      | abandoned |\n| 2 | Feb 21, 2023 09:15 PM | Feb 21, 2023 09:16 PM | side-project | completed |\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n**Note:**\n\n- Sessions that cross over to a new day will count towards that day's sessions.\n- A session with an empty end date indicates that the process was ended such a\n  way that a graceful shutdown was not possible.\n\n### ✒ Editing sessions\n\nYou can edit the tags of one or more sessions through the `edit-tag` command. It\naccepts the same options as the `list` command to select the sessions to be\nedited. The tags are command-line arguments. You will be prompted before the\nupdate is carried out.\n\nThe command below edits the tags of all sessions recorded `today` and tagged\nwith `writing`. It updates the tags for each session to writing, novel, and\n`once-upon-a-time`.\n\n```bash\nfocus edit-tag --tag 'writing' -p 'today' 'writing' 'novel' 'once-upon-a-time'\n```\n\n```text\n┌────────────────────────────────────────────────────────────────────────────────────────────────────┐\n| # | START DATE            | END DATE              | TAGGED                             | STATUS    |\n| 1 | Feb 21, 2023 09:16 PM | Feb 21, 2023 09:17 PM | writing · novel · once-upon-a-time | completed |\n| 2 | Feb 21, 2023 09:21 PM | Feb 21, 2023 09:22 PM | writing · novel · once-upon-a-time | completed |\n| 3 | Feb 21, 2023 09:22 PM | Feb 21, 2023 09:23 PM | writing · novel · once-upon-a-time | completed |\n└────────────────────────────────────────────────────────────────────────────────────────────────────┘\n WARNING  The sessions above will be updated. Press ENTER to proceed\n```\n\n### 🔥 Deleting sessions\n\nDeleting sessions is done in the same way as `list` except that `delete` is used\ninstead. You will be prompted to confirm the deletion before it is carried out.\n\n```bash\nfocus delete --start '2023-02-21 21:21:00'\n```\n\n```text\n┌─────────────────────────────────────────────────────────────────────────┐\n| # | START DATE            | END DATE              | TAGGED  | STATUS    |\n| 1 | Feb 21, 2023 09:22 PM | Feb 21, 2023 09:23 PM | writing | completed |\n| 2 | Feb 21, 2023 09:33 PM | Feb 21, 2023 09:33 PM |         | abandoned |\n└─────────────────────────────────────────────────────────────────────────┘\n WARNING  The above sessions will be deleted permanently. Press ENTER to proceed\n```\n\n## 🤝 Contribute\n\nBug reports and feature requests are much welcome! Please open an issue before\ncreating a pull request.\n\n## ⚖ Licence\n\nCreated by Ayooluwa Isaiah, and released under the terms of the\n[MIT Licence](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayoisaiah%2Ffocus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayoisaiah%2Ffocus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayoisaiah%2Ffocus/lists"}