{"id":18189858,"url":"https://github.com/bmedicke/pom","last_synced_at":"2025-04-02T05:32:48.735Z","repository":{"id":37040302,"uuid":"483987509","full_name":"bmedicke/pom","owner":"bmedicke","description":"command line pomodoro timer with vim keybindings, scriptable hooks, a web API, tmux support, json logging and more🍊⌛","archived":true,"fork":false,"pushed_at":"2022-06-20T10:00:58.000Z","size":4298,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-13T02:41:15.657Z","etag":null,"topics":["cli","command-line","command-line-tool","go","golang","home-assistant","json","pomodoro","pomodoro-timer","tmux","tui","vim","web-api","websocket"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bmedicke.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-21T09:26:24.000Z","updated_at":"2025-01-19T03:51:22.000Z","dependencies_parsed_at":"2022-06-25T08:05:27.023Z","dependency_job_id":null,"html_url":"https://github.com/bmedicke/pom","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmedicke%2Fpom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmedicke%2Fpom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmedicke%2Fpom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmedicke%2Fpom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bmedicke","download_url":"https://codeload.github.com/bmedicke/pom/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246763814,"owners_count":20829797,"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":["cli","command-line","command-line-tool","go","golang","home-assistant","json","pomodoro","pomodoro-timer","tmux","tui","vim","web-api","websocket"],"created_at":"2024-11-03T04:04:19.745Z","updated_at":"2025-04-02T05:32:48.453Z","avatar_url":"https://github.com/bmedicke.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pom\n\n*pom* is a command line [pomodoro](https://en.wikipedia.org/wiki/Pomodoro_Technique)\ntimer with vim keybindings, scriptable hooks, a web API, tmux support and json logging.\n\n![image](https://user-images.githubusercontent.com/173962/166680550-d70ed16a-bc93-414e-bf04-ad42abcf9f96.png)\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [installation](#installation)\n* [usage](#usage)\n* [flags](#flags)\n* [configuration](#configuration)\n  * [hooks](#hooks)\n  * [hook profiles](#hook-profiles)\n  * [show status in tmux](#show-status-in-tmux)\n  * [JSON logging](#json-logging)\n  * [Web API](#web-api)\n    * [home-assistant example](#home-assistant-example)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## installation\n\n```sh\ngo install github.com/bmedicke/pom@latest\n```\n\n## usage\n\n```sh\npom\n```\n\n* **keyboard shortcuts** are loosely based on Vim\n  * `hjklgG` move around\n  * `a`/`A`/`Enter` append to cell\n  * `cc` change cell\n  * `dd`/`dc` delete cell content\n  * `Esc` clear a key chord\n  * `;` next break/pomodoro\n  * `q` quit the program\n  * `Q` quit the program (don't save incomplete pomodoros)\n* while editing a cell [readline keybindings](https://en.wikipedia.org/wiki/GNU_Readline) are available\n  * `ctrl-a` jump to beginning\n  * `ctrl-e` jump to end\n  * `ctrl-k` delete to the right of cursor\n  * etc.\n\n## flags\n\n* `-h` show the help\n* `--profile \u003csubdir\u003e` select non-default [hook profile](#hook-profiles)\n* `--create-config` create config files, see [next section](#configuration)\n* `--longbreak-in \u003cuint\u003e` overwrite number of pomodoros required for the first long break\n\n\n## configuration\n\nCreate the config folder, config file and default hooks at `~/.config/pom/`:\n\n```sh\npom --create-config\n```\n\n### hooks\n\n* edit the scripts in `~/.config/pom/hooks/default`\n* the scripts are named after when they are called:\n  * `work_start`\n  * `work_done`\n  * `break_start`\n  * `break_done`\n  * `longbreak_start`\n  * `longbreak_done`\n  * `pomodoro_cancelled`\n* the interpreter (`sh`, `zsh`, `python3`, etc.) of the script is set via the [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix))\n\nHere are a couple of **usage scenarios** for hooks:\n\n  * start/stop your music (e.g. via `ncmpcpp`/`mpc`)\n  * toggle a light (e.g. via Home Assistant's `hass`)\n  * send a notification (via `prowl`'s REST API, etc.)\n  * set a Home Assistant `input_boolean` for further scripting\n\n### hook profiles\n\n* the `default` hooks profile is used when no other is specified\n* you can create custom hook profiles\n* e.g. a profile that toggles a light when pomodoros/breaks end:\n  * create a folder `~/.config/pom/hooks/light`\n  * add a `work_done` and a `break_done` script to it\n  * add your shell commands to toggle the light\n  * start *pom* with your profile:\n\n```sh\npom --profile light\n```\n\n### show status in tmux\n\n* if `writeTmuxFile` in `~/.config/pom/config.json` is set to `true`:\n  * *pom* keeps a file at `~/.config/pom/tmux` that always shows the current status\n  * when *pom* exits this file is emptied\n\nYou can `cat` this file into your tmux statusline:\n\n**.tmux.conf**\n```sh\nset -g status-right \"[#(cat ~/.config/pom/tmux)]\"\n```\n\n### JSON logging\n\n* if `logJSON` in `~/.config/pom/config.json` is set to `true`:\n  * *pom* logs all complete and incomplete pomodoros to: `~/.config/pom/log.json`\n\n**~/.config/pom/log.json**\n\n```json\n[\n  {\n    \"Project\": \"master thesis\",\n    \"Task\": \"research\",\n    \"Note\": \"mode locking\",\n    \"State\": \"work_done\",\n    \"Duration\": 60000000000,\n    \"StartTime\": \"2022-05-03T13:07:40.091129279+02:00\",\n    \"StopTime\": \"2022-05-03T13:08:40.285970461+02:00\"\n  },\n...\n```\n\n### Web API\n\n* disabled by default, edit `~/.config/pom/config.json`'s `enableAPI` to activate this feature\n* the API is still quite rudimentary\n* there are two endpoints that respond with JSON\n  * POST/GET `/continue`: starts the next state (same as pressing `;`)\n  * GET `/state`: returns json object that shows if a break or pom is in progress\n  * GET `/ws`: upgrades connection to a websocket and streams infos about the current pomodoro twice a second\n  * GET `/live`: open in browser to have a tab with the current timestamp in the title\n    * you can edit this script at: `~/.config/pom/static`\n\n![image](https://user-images.githubusercontent.com/173962/174577083-91933f53-b0f1-4325-ae56-1020e17817e2.png)\n\n```sh\nwebsocat ws://localhost:8421/ws | jq\n```\n\n```json\n{\n  \"Project\": \"pom\",\n  \"Task\": \"hide server from table if disabled\",\n  \"Note\": \"go lang\",\n  \"Duration\": 1500000000000,\n  \"StartTime\": \"2022-05-07T14:23:36.755337148+02:00\",\n  \"State\": \"work\",\n  \"StopTime\": \"0001-01-01T00:00:00Z\"\n}\n...\n```\n\n```sh\ncurl localhost:8421/continue # or call it from a bookmark, your phone, etc.\n```\n\n#### home-assistant example\n\n* here's an example for a minimalist home-assistant REST switch\n\n**configuration.yml**\n```yaml\nswitch:\n  - platform: rest\n    name: pom\n    resource: http://localhost:8421/continue\n    state_resource: http://localhost:8421/state\n    is_on_template: '{{ value_json.active }}'\n```\n\n![image](https://user-images.githubusercontent.com/173962/174577871-94716f32-bdb4-4eab-bcf1-3adaa77b0822.png)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmedicke%2Fpom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbmedicke%2Fpom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmedicke%2Fpom/lists"}