{"id":13858943,"url":"https://github.com/susam/timebox","last_synced_at":"2025-10-12T23:07:43.354Z","repository":{"id":8862782,"uuid":"10574119","full_name":"susam/timebox","owner":"susam","description":"A timer script for Windows/Linux/Unix/macOS to practice timeboxing (the time management technique)","archived":false,"fork":false,"pushed_at":"2020-12-15T17:09:31.000Z","size":61,"stargazers_count":44,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-22T17:48:56.092Z","etag":null,"topics":["batch-script","linux","macos","posix","productivity","shell-script","timeboxing","timer-script","unix","windows"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/susam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-08T20:51:23.000Z","updated_at":"2024-11-01T18:07:33.000Z","dependencies_parsed_at":"2022-09-13T10:40:11.190Z","dependency_job_id":null,"html_url":"https://github.com/susam/timebox","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftimebox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftimebox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftimebox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftimebox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/susam","download_url":"https://codeload.github.com/susam/timebox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243313,"owners_count":22038048,"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":["batch-script","linux","macos","posix","productivity","shell-script","timeboxing","timer-script","unix","windows"],"created_at":"2024-08-05T03:02:27.153Z","updated_at":"2025-10-12T23:07:38.312Z","avatar_url":"https://github.com/susam.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"Timebox\r\n=======\r\n\r\nTimebox is a timer script that may be used to practice timeboxing.\r\n\r\n[![Download][SHIELD_WIN]][DOWNLOAD_WIN]\r\n[![Download][SHIELD_UNX]][DOWNLOAD_UNX]\r\n[![Build Status][BUILD_IMG]][BUILD_URL]\r\n[![Coverage Status][COVERAGE_IMG]][COVERAGE_URL]\r\n\r\nThe Windows script has been tested on Windows 7 only. However, it should\r\nwork fine on other recent versions of Windows too.\r\n\r\nThe Unix script has been tested with [bash][], [ksh][] and [zsh][] on\r\nDebian and macOS as well as with [dash][], [posh][] and [yash][] on\r\nDebian. It should work fine on any Linux distribution as well as any\r\nPOSIX compliant system with a POSIX compliant shell.\r\n\r\n[SHIELD_WIN]: https://img.shields.io/badge/download-timebox%20for%20Windows-brightgreen.svg\r\n[SHIELD_UNX]: https://img.shields.io/badge/download-timebox%20for%20Unix-brightgreen.svg\r\n[DOWNLOAD_WIN]: https://github.com/susam/timebox/releases/download/0.5.0/timebox.cmd\r\n[DOWNLOAD_UNX]: https://github.com/susam/timebox/releases/download/0.5.0/timebox\r\n\r\n[BUILD_IMG]: https://travis-ci.org/susam/timebox.svg?branch=master\r\n[BUILD_URL]: https://travis-ci.org/susam/timebox\r\n[COVERAGE_IMG]: https://coveralls.io/repos/github/susam/timebox/badge.svg?branch=master\r\n[COVERAGE_URL]: https://coveralls.io/github/susam/timebox?branch=master\r\n\r\n[bash]: https://packages.debian.org/stable/bash\r\n[ksh]: https://packages.debian.org/stable/ksh\r\n[zsh]: https://packages.debian.org/stable/zsh\r\n[dash]: https://packages.debian.org/stable/dash\r\n[posh]: https://packages.debian.org/stable/posh\r\n[yash]: https://packages.debian.org/stable/yash\r\n\r\n\r\nContents\r\n--------\r\n\r\n* [Introduction](#introduction)\r\n* [Features](#features)\r\n* [Get Started](#get-started)\r\n* [Beeps](#beeps)\r\n* [Logs](#logs)\r\n* [Configuration](#configuration)\r\n* [License](#license)\r\n* [Support](#support)\r\n\r\n\r\nIntroduction\r\n------------\r\n\r\nTimeboxing is a time management technique that is believed to boost\r\nproductivity by limiting the time during which a task is supposed to be\r\ncompleted. A time box is a fixed period of time alloted for a task or\r\nactivity. The period of time to spend on the task is decided first. One\r\ntime box may last anywhere between 15 minutes to 45 minutes. The\r\nduration of a time box may depend on the task or activity.\r\nAlternatively, the task may be scoped in a manner that it can be\r\ncompleted in a fixed size time box. Then a timer is started with the\r\ndecided time interval. Once the timer notifies that the time interval\r\nhas expired, any activity or work on the task is stopped, and a short\r\nbreak is taken before beginning another time box.\r\n\r\nThis project offers scripts for Windows as well as Unix that may be used\r\nto run a time box for a specified duration.\r\n\r\n\r\nFeatures\r\n--------\r\n\r\n- Runs in Windows Command Prompt or Linux/Unix/macOS shell.\r\n- Boring user experience.\r\n- No frills.\r\n- No ~~bells and~~ whistles. Actually, there are bells (`printf \"\\a\"`).\r\n  See [Beeps](#beeps) for details.\r\n- Logs completed time boxes to a file named `timebox.log` in the user's\r\n  home directory.\r\n\r\n\r\nGet Started\r\n-----------\r\n\r\nTimebox is a single-file executable script.\r\n\r\nDownload [`timebox.cmd`][DOWNLOAD_WIN] for Windows,\r\nor [`timebox`][DOWNLOAD_UNX] for Linux, Unix, or macOS.\r\n\r\nCopy it to a directory specified in the `PATH` environment variable. On\r\nLinux/Unix/macOS, make the script executable: `chmod u+x timebox`.\r\n\r\nTo run a 30 minute time box, run the script without any arguments:\r\n\r\n    timebox\r\n\r\nThe script accepts an integer argument that specifies the duration of\r\nthe time box in minutes. For example, the following command also runs a\r\n30 minute time box:\r\n\r\n    timebox 30\r\n\r\nThe following command runs a 15 minute time box:\r\n\r\n    timebox 15\r\n\r\nThe time at which a time box ends and its duration is written to\r\n`%userprofile%\\timebox.log` on Windows and `~/timebox.log` on\r\nLinux/Unix/macOS at the end of a time box.\r\n\r\nThe following command runs a 30 minute box with a text comment that is\r\nrecorded in the log file when the time box ends.\r\n\r\n    timebox 30 write essay\r\n\r\nTo learn more about the usage of the script, run the following command.\r\n\r\n    timebox --help\r\n\r\nAfter the script starts, it displays a countdown starting with the\r\nspecified duration to 0. The countdown is displayed at the beginning of\r\na time box and whenever the number of minutes remaining in the time box\r\nis a multiple of 5. On Windows, the time remaining is also displayed in\r\nthe title bar of the Command Prompt window; the title bar is updated\r\nevery minute.\r\n\r\nHere is how a typical session looks on the terminal:\r\n\r\n    $ timebox\r\n    15:38:24 - 30\r\n    15:43:24 - 25\r\n    15:48:24 - 20\r\n    15:53:24 - 15\r\n    15:58:24 - 10\r\n    16:03:24 - 05\r\n    16:08:24 - 00\r\n    :-) :-) :-) :-) :-)\r\n    $\r\n\r\nApart from writing to standard output as shown above, the script also\r\nbeeps a few times. The beeping behaviour is explained in the next\r\nsection.\r\n\r\n\r\nBeeps\r\n-----\r\n\r\nTwo beeps are played at the beginning of a time box. If the duration of\r\nthe time box is longer then 15 minutes, one beep is played when 15\r\nminutes are remaining in the time box. If the duration of the time box\r\nis longer than 5 minutes, two beeps are played when 5 minutes are\r\nremaining in the time box. Four beeps are played at the end of a time\r\nbox. A dialog box with smileys is displayed for ten seconds at the end\r\nof a time box.\r\n\r\n\r\nConfiguration\r\n-------------\r\n\r\nThe behaviour of the script can be tweaked a little bit with a\r\nconfiguration file at `~/.timeboxrc`, i.e., `%userprofile%\\.timeboxrc`\r\non Windows and `$HOME/.timeboxrc` on Linux/Unix/macOS.\r\n\r\nThe script recognizes the following keywords (configuration options) in\r\nthe configuration file.\r\n\r\n  - `quiet` - Do not beep in the middle of a time box. Without this\r\n    option, the script beeps once when 15 minutes are left and twice\r\n    more when 5 minutes are left. This can be distracting on macOS where\r\n    the beeps cause the icon for the terminal running the script to\r\n    bounce in the Dock. With this configuration option, the beeps occur\r\n    only at the start and the end of a time box.\r\n\r\n  - `sober` - Display the message \"EOT\" instead of smileys when a time\r\n    box ends.\r\n\r\nA configuration keyword may occur anywhere in the configuration file.\r\nThe only requirement is that the keyword must appear as a word, i.e., it\r\nmust either occur at the beginning of a line or follow a whitespace\r\ncharacter and it must also either occur at the end of a line or followed\r\nby a whitespace character. Therefore, multiple configuration keywords\r\nmay occur in the same line or on different lines. Any text in the\r\nconfiguration file that is not a configuration keyword is ignored.\r\n\r\n\r\nLicense\r\n-------\r\n\r\nThis is free and open source software. You can use, copy, modify,\r\nmerge, publish, distribute, sublicense, and/or sell copies of it,\r\nunder the terms of the MIT License. See [LICENSE.md][L] for details.\r\n\r\nThis software is provided \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\r\nexpress or implied. See [LICENSE.md][L] for details.\r\n\r\n[L]: LICENSE.md\r\n\r\n\r\nSupport\r\n-------\r\n\r\nTo report bugs, suggest improvements, or ask questions, please create a\r\nnew issue at \u003chttp://github.com/susam/timebox/issues\u003e.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsusam%2Ftimebox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsusam%2Ftimebox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsusam%2Ftimebox/lists"}