{"id":28146832,"url":"https://github.com/susam/tzero","last_synced_at":"2025-09-06T19:34:23.211Z","repository":{"id":246797236,"uuid":"823355141","full_name":"susam/tzero","owner":"susam","description":"Social timeboxing for IRC channels","archived":false,"fork":false,"pushed_at":"2024-09-08T20:42:09.000Z","size":87,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-25T13:50:51.942Z","etag":null,"topics":["irc","productivity","python","timeboxing"],"latest_commit_sha":null,"homepage":"https://web.libera.chat/#bitwise","language":"Python","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-02T22:07:55.000Z","updated_at":"2024-09-08T20:42:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"10c6c08c-377c-40c9-98cc-75b8dcac4e7e","html_url":"https://github.com/susam/tzero","commit_stats":null,"previous_names":["susam/tzero"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftzero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftzero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftzero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/susam%2Ftzero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/susam","download_url":"https://codeload.github.com/susam/tzero/tar.gz/refs/heads/main","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":["irc","productivity","python","timeboxing"],"created_at":"2025-05-14T23:14:38.594Z","updated_at":"2025-05-14T23:15:50.308Z","avatar_url":"https://github.com/susam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Tzero\n=====\n\nTzero is a timeboxing manager for IRC channels.  This tool connects to\nan IRC network as a client and functions as an IRC bot.  Users of the\nchannel may send bot commands like `,begin`, `,list`, `,mine`,\n`,running`, etc. to manage and view their timeboxes.\n\nTimeboxing is a time management technique that is believed to boost\nproductivity by limiting the time during which a task is supposed to\nbe completed.  A timebox is a fixed period of time alloted for a task\nor activity.  This tool lets users of an IRC channel start and manage\ntheir timeboxes while they block off some focus time for productive\nwork.\n\nThere is a very popular time management technique known as the\n[Pomodoro Technique] which is closely related to the timeboxing\ntechnique.  The Pomodoro Technique prescribes specific guidelines like\n25 minute timeboxes, 5 minute break after each timebox, a longer break\nafter every 4 timeboxes, etc.  This tool, however, supports timeboxing\nin general without any specific guidelines.  But if you wish to\npractice the Pomodoro Technique with this tool, it is definitely\npossible to do so since this tool is, after all, a simple timer bot\nfor IRC.\n\nTo try Tzero right now, head over to the [Try It Now](#try-it-now)\nsection.\n\n[Pomodoro Technique]: https://en.wikipedia.org/wiki/Pomodoro_Technique\n\n\nContents\n--------\n\n* [Try It Now](#try-it-now)\n* [Example Session](#example-session)\n* [Features](#features)\n* [Commands](#commands)\n  * [begin](#begin)\n  * [cancel](#cancel)\n  * [delete](#delete)\n  * [list](#list)\n  * [mine](#mine)\n  * [running](#running)\n  * [summary](#summary)\n  * [time](#time)\n  * [help](#help)\n  * [version](#version)\n* [Setup](#setup)\n* [Configuration](#configuration)\n* [NIMB Support](#nimb-support)\n* [License](#license)\n* [Support](#support)\n* [Channels](#channels)\n* [More](#more)\n\n\nTry It Now\n----------\n\nTo see Tzero in action, join either of the two channels:\n\n- Libera chat: [#bitwise](https://web.libera.chat/#bitwise)\n- Matrix bridge: [#bitwise:matrix.org](https://app.element.io/#/room/#bitwise:matrix.org)\n\nYou need to join only one of these links, not both.  Messages posted\nto the IRC channel are automatically forwarded to the Matrix room and\nvice versa.\n\nIf you are not an active IRC user, prefer joining the Matrix bridge\nbecause it is more convenient for someone unfamiliar with IRC.  For\nexample, you can close your web browser or client and your Matrix chat\nsession will still stay alive on the server.  You can connect back\nlater and read messages that were sent to the room while you were\naway. Doing that with IRC requires slightly more work such as setting\nup IRC bouncers etc.\n\nAfter connecting to the above IRC channel (or the Matrix room), send\nthe message `,help` to the channel.  An instance of Tzero is connected\nto the channel with the nickname `t0` and it will respond to your\nmessage as soon as it reads it.\n\n\nExample Session\n---------------\n\n```\n20:07 \u003csusam\u003e ,begin Read \"Galois Theory\" by Stewart (2015)\n20:07 \u003ct0\u003e Started timebox in #bitwise: susam [Sun 20:07 GMT] (30 min) Read \"Galois Theory\" by Stewart (2015)\n20:37 \u003ct0\u003e Completed timebox in #bitwise: susam [Sun 20:07 GMT] (30 min) Read \"Galois Theory\" by Stewart (2015)\n20:39 \u003csusam\u003e ,list\n20:39 \u003ct0\u003e Completed timeboxes in #bitwise:\n20:39 \u003ct0\u003e susam [Sun 20:07 GMT] (30 min) Read \"Galois Theory\" by Stewart (2015)\n20:39 \u003ct0\u003e susam [Sun 19:27 GMT] (30 min) Read \"Introduction to Analytic Number Theory\" by Apostol (1976)\n20:39 \u003ct0\u003e gigo [Sun 18:51 GMT] (30 min) Add Vertico to my Emacs setup\n20:39 \u003ct0\u003e gigo [Sun 16:09 GMT] (30 min) Read https://go.dev/tour/concurrency/1\n20:39 \u003ct0\u003e drwiz [Sun 16:09 GMT] (30 min) Solve the N Queens Problem in C++\n20:40 \u003csusam\u003e ,summary\n20:40 \u003ct0\u003e I have run 15 timeboxes across all channels, totalling 900 minutes.  The average length of each timebox is 30 minutes.\n```\n\n\nFeatures\n--------\n\n* Basic timeboxing: Tzero supports commands like `begin` and `cancel`\n  to start a timebox and cancel a timebox before its completion (say,\n  if you change your mind about it), respectively.  The `list` command\n  lets you list all completed timeboxes in the current channel.  The\n  `mine` command lets you list your own completed timeboxes in the\n  current channel.\n\n* Multi-channel: Tzero can log into multiple channels simultaneously\n  and track timeboxes started by users of each channel separately.\n\n* Channel isolation: Timeboxes are scoped to the channel where the\n  timebox was started.  A user connected to one channel cannot see or\n  list running or completed timeboxes on another channel.\n\n* Private timeboxing: Users can run timeboxes privately by sending\n  private messages to Tzero with `/msg` or `/query` commands.  A\n  private message session is treated like a virtual private channel,\n  so it too benefits from the channel isolation feature.\n\n* Persistent state: Data pertaining to running and completed timeboxes\n  are saved to a configurable state file.  As a result, if the tool\n  stops for any reason, it continues to track the timeboxes, as if\n  nothing happened, after it restarts.\n\n* Limited retention: Within each channel or private message session,\n  only a certain number of most recent timeboxes started within a\n  certain amount of time are kept in the state file.  Older timeboxes\n  are permanently deleted from the state.  Both the number of recent\n  timeboxes to keep and the retention duration are configurable.\n\n* One timebox per user per channel at a time: Within a channel, a user\n  can run a maximum of only one timebox at a time.  However, the same\n  user can run multiple timeboxes simultaneously as long as they are\n  in different channels.\n\n\nCommands\n--------\n\nTzero supports several commands like `begin`, `list`, `summary`, etc.\nCommands must begin with a prefix string.  In the example presented in\nsection [Example Session](#example-session), the prefix string is `,`\n(the comma).  The prefix string needs to be configured in the\nconfiguration file.  See section [Configuration](#configuration) for\nmore details.\n\nA command name may be truncated to any positive length.  For example,\nthe `begin` command may be written as `b`, `be`, `beg`, or `begi` too.\n\nThe following sections present the complete list of commands supported\nby Tzero.\n\n\n### begin\n\nUsage: `begin [MINUTES] SUMMARY`\n\nStart a new timebox for the specified number of `MINUTES`.  `MINUTES`\nmust be a multiple of 5 between 15 and 60, inclusive.  If `MINUTES` is\nnot specified, default to 30 minutes.\n\nExamples:\n\n  - `,begin Read SICP`\n  - `,begin 45 Review article`\n  - `,beg Read Galois Theory`\n  - `,b Write blog post`\n\n\n### cancel\n\nUsage: `cancel`\n\nCancel your currently running timebox in the current channel.  No\nrecord of your cancelled timebox is kept in the internally maintained\ntimeboxing history.\n\nIn a private message session, this command cancels your running\ntimebox in the private message session.\n\n\n### delete\n\nUsage: `delete`\n\nDelete your last completed timebox in current channel.  This removes\nthe record of your last completed timebox from timeboxing history.  A\ndeleted timebox cannot be listed with the `list` and `mine` commands\ndescribed in the next two sections.\n\nIn a private message session, this command deletes your last completed\ntimebox that you ran in the private message session.\n\n\n### list\n\nUsage: `list`\n\nList completed timeboxes in current channel.\n\nIn a private message session, this command lists your completed\ntimeboxes that you ran in a private message session.\n\n\n### mine\n\nUsage: `mine`\n\nList only your completed timeboxes in the current channel.\n\nIn a private message session, this command lists your completed\ntimeboxes that you ran in a private message session.  Note that in a\nprivate message session, the `list` and `mine` commands present the\nsame list of timeboxes.\n\n\n### running\n\nUsage: `running`\n\nList all running timeboxes of the channel.\n\nIn a private message session, this command lists your running timebox\nin the private message sesion only.\n\n\n### summary\n\nUsage: `summary`\n\nShow a summary of all timeboxes completed across all channels.\n\nThe summary information presents only the total number of completed\ntimeboxes and total number of minutes completed in these timeboxes.\nThe average length of each timebox is presented too.  No other data is\nexposed by this command.  The summary data includes the timeboxes\ncompleted in private message sessions too.\n\n\n### time\n\nUsage: `time`\n\nShow current UTC time.\n\n\n### help\n\nUsage: `help [COMMAND]`\n\nShow usage information about the specified `COMMAND`.\n\nThe specified `COMMAND` may or may not contain the Tzero prefix\nstring.  The prefix-free form of the command is accepted too as\n`COMMAND` by the `help` command, i.e., both `,help ,begin` and\n`,help begin` are valid commands when the prefix is `,`.\n\nFurther, the command name may be truncated to any positive length,\ni.e., `,help ,b`, `,help b`, `,help` etc. are valid commands when the\nprefix is `,`.\n\nExamples:\n\n  - `,help`\n  - `,help ,begin`\n  - `,help begin`\n  - `,help ,b`\n  - `,help b`\n\n\n### version\n\nUsage: `version`\n\nShow version, copyright, and license details.\n\n\nSetup\n-----\n\nPerform the following steps to set up Tzero for your IRC channels:\n\n 1. Clone this repository.  For example,\n\n    ```sh\n    git clone https://github.org/susam/tzero.git\n    ```\n\n 2. Create configuration file:\n\n    ```sh\n    cd tzero\n    cp etc/tzero.json tzero.json\n    ```\n\n    Then edit the new configuration file named `tzero.json` to include\n    connection details for the IRC nick that should be used to connect\n    to an IRC network.  Some example values are already populated in\n    this file to help you get started.\n\n 3. Run Tzero:\n\n    ```sh\n    python3 tzero.py\n    ```\n\nNote that Tzero does not depend on any external Python library or\npackage.  It only depends on a recent version of Python 3 and its\nstandard library.\n\n\nConfiguration\n-------------\n\nTzero reads its configuation from a file named `tzero.json` in the\ncurrent working directory.  See [etc/tzero.json](etc/tzero.json) for a\nsimple example configuration.  Here is a brief explanation of each\nconfiguration field in this file:\n\n- `host` (type `string`): Hostname to be used to connect to the IRC\n  network.\n\n- `port` (type `number`): TCP port number to be used to connect to the\n  IRC network.\n\n- `tls` (type `boolean`): Whether to use TLS to connect to the IRC\n  network.\n\n- `nick` (type `string`): Nickname to assume while connecting to the\n  IRC network.\n\n- `password` (type `string`): Password to use while connecting to IRC\n  network.\n\n- `channels` (type `array` of `string`): A list of IRC channels to\n  connect to.\n\n- `state` (type `str`): Path of a file where Tzero should save its\n  state to.\n\n- `keep_timeboxes` (type `number`): Maximum number of recent timeboxes\n  per user per channel to retain in state.  Older timeboxes are\n  permanently deleted from the state.\n\n- `keep_duration_seconds` (type `number`): Maximum duration (in\n  seconds) for which recent timeboxes are retained in state.  Older\n  timeboxes are permanently deleted from the state.\n\n- `max_print_channel` (type `number`): Maximum number of timeboxes to\n  be listed in a channel in response to `list` or `mine` commands.\n\n- `max_print_private` (type `number`): Maximum number of timeboxes to\n  be listed in private message in response to `list` or `mine`\n  commands.\n\n- `default_duration_minutes` (type `number`): Duration of a timebox\n  when no duration is specified in the `begin` command sent by the\n  user.\n\n- `duration_multiple_minutes` (type `number`): Duration specified in\n  the `begin` command must be a multiple of this number, otherwise the\n  `begin` command is rejected with an error.\n\n- `min_duration_minutes` (type `number`): Minimum allowed duration of\n  a timebox.\n\n- `max_duration_minutes` (type `number`): Maximum allowed duration of\n  a timebox.\n\n- `prefix` (type `str`): A prefix string that begins all Tzero\n  commands.\n\n- `nimb` (type `str`): Nickname of any [NIMB][] client that is present\n  in the channel.  If no NIMB client is present, set this to an empty\n  string.  See section [NIMB Support](#nimb-support) below for more\n  details about this.\n\n- `block` (type `array` of `string`): A list of strings to be blocked.\n  If an IRC user sends a Tzero command that contains any string\n  mentioned in this list, then Tzero rejects that command.\n\n[NIMB]: https://github.com/susam/nimb\n\n\nNIMB Support\n------------\n\n[NIMB][] is a relay bridge client that can forward messages between\nIRC channels and Matrix rooms.  If Tzero is connected to an IRC\nchannel that is bridged to a Matrix room using NIMB, then Tzero can be\nconfigured to accept commands arriving from Matrix users via NIMB.  To\ndo so, the `nimb` configuration option must be configured as explained\nin the previous section.\n\nThere is one thing to be careful about while enabling NIMB support\nthough.  The [infix](https://github.com/susam/nimb#configuration-keys)\nfor the Matrix room must be set to an empty string in the NIMB\nconfiguration.  Tzero cannot support Matrix rooms bridged via NIMB\nthat have a non-empty infix in the NIMB configuration.\n\n\nLicense\n-------\n\nThis is free and open source software.  You can use, copy, modify,\nmerge, publish, distribute, sublicense, and/or sell copies of it,\nunder the terms of the MIT License.  See [LICENSE.md][L] for details.\n\nThis software is provided \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nexpress or implied.  See [LICENSE.md][L] for details.\n\n[L]: LICENSE.md\n\n\nSupport\n-------\n\nTo report bugs, suggest improvements, or ask questions, please create\na new issue at \u003chttp://github.com/susam/tzero/issues\u003e.\n\n\nChannels\n--------\n\nThe author of this project hangs out at the following places online:\n\n- Website: [susam.net](https://susam.net)\n- Mastodon: [@susam@mastodon.social](https://mastodon.social/@susam)\n- GitHub: [@susam](https://github.com/susam)\n- Matrix: [#susam:matrix.org](https://app.element.io/#/room/#susam:matrix.org)\n- IRC: [#susam:libera.chat](https://web.libera.chat/#susam)\n\nYou are welcome to subscribe to, follow, or join one or more of the\nabove channels to receive updates from the author or ask questions\nabout this project.\n\n\nMore\n----\n\nSee [NIMB](https://github.com/susam/nimb), a relay bridge to forward\nmessages between IRC channels and Matrix rooms.\n\nSee [Clog](https://github.com/susam/clog), an extremely simple IRC\nchat logger.\n\nSee [Timebox](https://github.com/susam/timebox) for timeboxing scripts\nfor Unix/Linux/macOS/Windows.\n\n\n\u003c!--\n- Update version in pyproject.toml and tzero.py.\n\n- Update CHANGES.md.\n\n- Run the following commands:\n\n  make checks\n\n  git add -p\n  git status\n  git commit\n  git push -u origin main\n\n  make dist test-upload verify-test-upload\n  make dist upload verify-upload\n\n  VER=$(grep version pyproject.toml | cut -d '\"' -f2)\n  echo $VER\n  git tag $VER -m \"Tzero $VER\"\n  git push origin main $VER\n\n  git remote add cb https://codeberg.org/susam/tzero.git\n  git push cb --all\n  git push cb --tags\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsusam%2Ftzero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsusam%2Ftzero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsusam%2Ftzero/lists"}