Skip to content

Latest commit

 

History

History
183 lines (141 loc) · 4.97 KB

readme.md

File metadata and controls

183 lines (141 loc) · 4.97 KB
Raw

pom

pom is a command line pomodoro timer with vim keybindings, scriptable hooks, a web API, tmux support and json logging.

image

installation

go install github.com/bmedicke/pom@latest

usage

pom
  • keyboard shortcuts are loosely based on Vim
    • hjklgG move around
    • a/A/Enter append to cell
    • cc change cell
    • dd/dc delete cell content
    • Esc clear a key chord
    • ; next break/pomodoro
    • q quit the program
    • Q quit the program (don't save incomplete pomodoros)
  • while editing a cell readline keybindings are available
    • ctrl-a jump to beginning
    • ctrl-e jump to end
    • ctrl-k delete to the right of cursor
    • etc.

flags

  • -h show the help
  • --profile <subdir> select non-default hook profile
  • --create-config create config files, see next section
  • --longbreak-in <uint> overwrite number of pomodoros required for the first long break

configuration

Create the config folder, config file and default hooks at ~/.config/pom/:

pom --create-config

hooks

  • edit the scripts in ~/.config/pom/hooks/default
  • the scripts are named after when they are called:
    • work_start
    • work_done
    • break_start
    • break_done
    • longbreak_start
    • longbreak_done
    • pomodoro_cancelled
  • the interpreter (sh, zsh, python3, etc.) of the script is set via the shebang

Here are a couple of usage scenarios for hooks:

  • start/stop your music (e.g. via ncmpcpp/mpc)
  • toggle a light (e.g. via Home Assistant's hass)
  • send a notification (via prowl's REST API, etc.)
  • set a Home Assistant input_boolean for further scripting

hook profiles

  • the default hooks profile is used when no other is specified
  • you can create custom hook profiles
  • e.g. a profile that toggles a light when pomodoros/breaks end:
    • create a folder ~/.config/pom/hooks/light
    • add a work_done and a break_done script to it
    • add your shell commands to toggle the light
    • start pom with your profile:
pom --profile light

show status in tmux

  • if writeTmuxFile in ~/.config/pom/config.json is set to true:
    • pom keeps a file at ~/.config/pom/tmux that always shows the current status
    • when pom exits this file is emptied

You can cat this file into your tmux statusline:

.tmux.conf

set -g status-right "[#(cat ~/.config/pom/tmux)]"

JSON logging

  • if logJSON in ~/.config/pom/config.json is set to true:
    • pom logs all complete and incomplete pomodoros to: ~/.config/pom/log.json

~/.config/pom/log.json

[
  {
    "Project": "master thesis",
    "Task": "research",
    "Note": "mode locking",
    "State": "work_done",
    "Duration": 60000000000,
    "StartTime": "2022-05-03T13:07:40.091129279+02:00",
    "StopTime": "2022-05-03T13:08:40.285970461+02:00"
  },
...

Web API

  • disabled by default, edit ~/.config/pom/config.json's enableAPI to activate this feature
  • the API is still quite rudimentary
  • there are two endpoints that respond with JSON
    • POST/GET /continue: starts the next state (same as pressing ;)
    • GET /state: returns json object that shows if a break or pom is in progress
    • GET /ws: upgrades connection to a websocket and streams infos about the current pomodoro twice a second
    • GET /live: open in browser to have a tab with the current timestamp in the title
      • you can edit this script at: ~/.config/pom/static

image

websocat ws://localhost:8421/ws | jq
{
  "Project": "pom",
  "Task": "hide server from table if disabled",
  "Note": "go lang",
  "Duration": 1500000000000,
  "StartTime": "2022-05-07T14:23:36.755337148+02:00",
  "State": "work",
  "StopTime": "0001-01-01T00:00:00Z"
}
...
curl localhost:8421/continue # or call it from a bookmark, your phone, etc.

home-assistant example

  • here's an example for a minimalist home-assistant REST switch

configuration.yml

switch:
  - platform: rest
    name: pom
    resource: http://localhost:8421/continue
    state_resource: http://localhost:8421/state
    is_on_template: '{{ value_json.active }}'

image