{"id":20230616,"url":"https://github.com/cdepillabout/break-time","last_synced_at":"2025-04-06T06:08:32.689Z","repository":{"id":44583029,"uuid":"236988896","full_name":"cdepillabout/break-time","owner":"cdepillabout","description":"break timer that forces you to take a break","archived":false,"fork":false,"pushed_at":"2025-02-19T02:38:33.000Z","size":390,"stargazers_count":19,"open_issues_count":14,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T04:11:10.456Z","etag":null,"topics":["break-time","break-timer","daemon","hacktoberfest","linux","rust","x11"],"latest_commit_sha":null,"homepage":"https://functor.tokyo/break-time","language":"Rust","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/cdepillabout.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null}},"created_at":"2020-01-29T13:31:03.000Z","updated_at":"2025-02-19T02:38:37.000Z","dependencies_parsed_at":"2025-02-19T03:34:56.741Z","dependency_job_id":null,"html_url":"https://github.com/cdepillabout/break-time","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdepillabout%2Fbreak-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdepillabout%2Fbreak-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdepillabout%2Fbreak-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdepillabout%2Fbreak-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdepillabout","download_url":"https://codeload.github.com/cdepillabout/break-time/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441052,"owners_count":20939239,"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":["break-time","break-timer","daemon","hacktoberfest","linux","rust","x11"],"created_at":"2024-11-14T07:43:12.798Z","updated_at":"2025-04-06T06:08:32.669Z","avatar_url":"https://github.com/cdepillabout.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# break-time\n\n[![Actions Status](https://github.com/cdepillabout/break-time/workflows/CI/badge.svg)](https://github.com/cdepillabout/break-time/actions)\n[![crates.io](https://img.shields.io/crates/v/break-time.svg)](https://crates.io/crates/break-time)\n[![dependency status](https://deps.rs/repo/github/cdepillabout/break-time/status.svg)](https://deps.rs/repo/github/cdepillabout/break-time)\n![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)\n\nbreak-time is an application that forces you to take breaks while working at\nyour computer.  This is convenient for people that want to avoid sitting for\ntoo long, or staring at the computer screen for too long.\n\nThe main feature of break-time is that there is no easy way to end a break\nearly.  Once a break starts, you are forced to stop using your computer.\nHowever, there are plugins provided to avoid breaks at inconvenient times.  For\ninstance, there is a plugin to avoid having a break occur during a time when\nyou have an event on your Google Calendar, as well as a plugin to avoid a break\nwhen you are on a video chat in Google Meet, Zoom, etc.\n\nbreak-time currently only runs on Linux with X11.  However, PRs are welcome\nadding support for other platforms and window systems.\n\n## Installing\n\nbreak-time requires a few system libraries to be available.  On Debian/Ubuntu systems, these can be installed with the following command:\n\n```console\n$ sudo apt-get install libgtk-3-dev libxcb-screensaver0-dev\n```\n\nAfter this, you can install break-time with\n[`cargo`](https://doc.rust-lang.org/cargo/):\n\n```console\n$ cargo install break-time\n```\n\n## Usage\n\nOnce break-time is installed, I suggest running it once so that it creates a\nconfiguration file.  Immediately kill it with \u003ckbd\u003eCtrl\u003c/kbd\u003e-\u003ckbd\u003eC\u003c/kbd\u003e after\nrunning it.\n\n```console\n$ break-time\n^C\n```\n\nbreak-time should create a configuration file in\n`~/.config/break-time/config.toml`.  Open up this configuration file in a text\neditor to see what options are available.  If the explanations for any options\nare not understandable, please open an issue.\n\nThe most interesting option will probably be `accounts` (or\n`plugin.google_calendar.accounts`).  This is described in the next section.\n\nAfter you have configured break-time, run it again.\n\n```console\n$ break-time\n```\n\nbreak-time will countdown until it is time for the next break.\n\nbreak-time will create a systray icon.  If you mouse over it, it will tell you\nhow many minutes are left until your next break.  If you right click on the\nsystray icon, you can pause and resume the break countdown timer.\n\nWhen it is time for your next break, break-time will pop up a screen telling\nyou to take a break.  You won't be able to close this screen until either the\nbreak-time is over, or you press the spacebar 400 times.\n\n### Plugins\n\nbreak-time has plugins that are used to prevent a break from occurring.  Right\nbefore a break is about to occur, break-time queries all the plugins and asks\nif it is really okay to start a break.  This section explains how the plugins\nwork and how to configure them.\n\n#### X Window Titles (Video Chat)\n\nThe X Window Title plugin checks whether or not there is an X Window with a\ngiven name and title.\n\nThis is convenient to stop a break from occurring when you're in a video chat.\n\nCurrently, this plugin only checks for a few specific window names and titles.\nYou can see what window names and titles are checked for in\n[this function](https://github.com/cdepillabout/break-time/blob/master/src/scheduler/plugins/window_titles.rs#L159-L193).\n\nIf you want additional applications to be supported, please open an\nissue or send a PR modifying this function.\n\nOne way to check if this plugin is working is start break-time with a short\nbreak interval, and then open https://meet.google.com/ in Firefox or Chromium.\nbreak-time should not start a break while https://meet.google.com/ is open (and\nthe currently focused tab).\n\n#### Google Calendar\n\nThe Google Calendar plugin checks whether or not there is an event on your\nGoogle Calendar currently occurring.  If there is an event, the plugin stops\nbreak-time from starting a break.\n\nThis is convenient to stop a break from happening when you're in a meeting at\nwork.\n\nThis plugin has a feature where if your Google Calendar event has a description\nwith the magic string `ignore break-time`, break-time will ignore it when\nconsidering whether or not to start a break.\n\nThis plugin requires some configuration before it can be used.  First, you must\nadd your Gmail address to the break-time configuration file,\n`~/.config/break-time/config.toml`.  The `accounts` (or\n`plugin.google_calendar.accounts`) field should be set to a list of your Gmail\naddresses.  I suggest only adding one at a time.\n\nIf your Gmail address is `example@gmail.com`, the configuration file will look\nlike the following:\n\n```toml\n[plugin.google_calendar]\naccounts = [ \"example@gmail.com\", ]\n```\n\nAfter adding this, restart break-time.  break-time should output a message like\nthe following:\n\n```console\n$ break-time\nPlease direct your browser to https://accounts.google.com/o/oauth2/auth... and follow the instructions displayed there.\n```\n\nMake sure you are signed in to `example@gmail.com` in your browser (and not\nanother email address). Follow the link.  You should be presented with a\n\"Choose an account\" page (as long as you have multiple Gmail accounts).  Make\nsure you choose `example@gmail.com`.\n\nNext, you'll be presented with a warning that the break-time app is not\nverified.  Click the \"Advanced\" link, and then \"Go to Break Time (unsafe)\".\n\n(This is currently necessary because I haven't completed the verification\nrequest from Google for use of the Google Calendar API.  See issue\n[#11](https://github.com/cdepillabout/break-time/issues/11) for slightly more\ninformation.)\n\nThe next screen will ask you to grant break-time the following two permissions:\n\n-   View events on all your calendars\n\n    This allows break-time to check the start and end times of the events on\n    your calendar.\n\n-   View your calendars\n\n    This allows break-time to determine what calendars you have, in order to\n    determine where to check for events.\n\nOnce you grant break-time these permissions, break-time will save an OAuth\ntoken to disk in `~/.cache/break-time/google-calendar/`.  This will allow\nbreak-time to continue checking your Google Calendar without having to go\nthrough this authorization step again in the future.\n\nNote that break-time doesn't store your calendar data on disk, and it\ndefinitely doesn't transmit it over the network after receiving it from the\nGoogle Calendar API.  If you're worried about using this plugin, I'd recommend\nreading the source code of the\n[`google_calendar.rs`](https://github.com/cdepillabout/break-time/blob/master/src/scheduler/plugins/google_calendar.rs).\nThe only security concern is that break-time stores an OAuth token to disk so\nthat it can re-use it next time you start break-time.\n\nIf you want to use break-time with multiple Google Calendar accounts, you can\nadd multiple addresses to `plugin.google_calendar.accounts`.  Although, I suggest\nonly adding an account and doing authorization one at a time.\n\nOne way to check if this plugin is working is to set a short break interval,\nand create an event on your calendar.  break-time should not start a break\nwhile an event is taking place.\n\n## Why\n\nI noticed I was sitting in front of my computer for excessively long periods of\ntime.  I thought this was starting to lead to neck and shoulder pain, so I\nwanted to find a way to force myself to take more breaks.\n\nI tried a couple solutions, including a manual kitchen timer, timers on my\nphone, applications like [Stretchly](https://hovancik.net/stretchly/), etc.\nHowever, I've never found anything that really worked well.\n\nI have three main problems with other solutions:\n\n-   It is too easy to ignore the breaks.  When using a timer on my phone, I\n\twould often turn off the alarm and continue working.  When using Stretchly,\n    I would often exit out of it whenever a break started.\n\n    break-time fixes this by making it really hard to skip breaks.  Once a\n    break starts, you're forced to step away from your computer.\n\n-   Breaks occur at inconvenient times.  You never want a break to occur when\n    you're doing something important, like in a meeting or in a video chat.\n\n    break-time fixes this by having plugins to detect when you're in a meeting\n    or in a video chat.\n\n-   There is no warning that a break is coming.  With other solutions, it is\n    frustrating when a break suddenly occurs in the middle of your work.\n\n    break-time fixes this by having a countdown timer in the systray icon.\n    You get a five-minute heads-up to wrap up any code you're writing,\n    messages you're writing on Slack, documentation you're reading, etc.\n\nbreak-time is one of the first non-trivial Rust programs I've created,\ncurrently at around 2,500 lines (including whitespace and comments).\n\nThe main difficulty in writing break-time was trying to find a good abstraction\nto deal with all the concurrent code.  In the end, I don't feel like I was able\nto do this, but I created\n[an issue](https://github.com/cdepillabout/break-time/issues/5) to think of how\nto improve this.\n\n## Contributions\n\nFeel free to open an issue or PR for any\nbugs, problems, suggestions, or improvements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdepillabout%2Fbreak-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdepillabout%2Fbreak-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdepillabout%2Fbreak-time/lists"}