RFC: Command Hooks

[justincampbell]

It would be nice to be able to associate any functionality you wanted when a pomodoro was started/completed, and we could accomplish that through hooks which execute shell commands.

Commands

There are a few commands where this makes sense:

• Starting
  • start - Start a new Pomodoro
  • repeat - Repeat the last Pomodoro
• Stopping
  • finish - Finish the current Pomodoro
  • cancel - Cancel the current Pomodoro
  • break - Take a break

start

Start is fairly straightforward, as it would exec the given command when the start command is passed.

repeat

Repeat would function the same way as start (it also delegates to start internally).

finish

Finish is a command which modifies the duration of the pomodoro to be now - start_time, effectively changing the end time to now. Typically I use it to finish a pomodoro early or late. Most of the time I never use this command, and instead just see that the pomodoro has ended and go take a break.

Adding a hook to finish would either require either A) the user to use the finish command or B) a daemon which watches for pomodoros finishing and then runs commands.

I would not like to do B, because on top of adding a lot more complexity to run the manage the background process, there could also be running in a different environment, which would make some exec commands fail unexpectedly. But I'm not opposed to it.

cancel

Cancel effectively undos the last pomodoro. I think this should run the same hook as finish.

break

I think it makes sense to merge finish and break together, since they are both things you do at the end of the pomodoro. At the very least, finish should have a --break flag which defaults to true or 5m (#7).

Hooks

We could introduce 2 hook settings, representing a start or finish/end:

start_hook="say starting"
end_hook="say done"

Multiple hooks

It should be possible to declare multiple hooks for the same event:

start_hook=slack -dnd 25m
start_hook=~/dnd.sh on
end_hook=~/dnd.sh off

[chrisroberts]

Would be nice to include some context when calling the hooks. Having the description, tags, duration, etc. would likely be useful for scripts in a variety of ways. Setting them in POMODORO_ prefixed environment variables seems like an easy and unobtrusive way to provide them.

[justincampbell]

I'm going to work on this soon, but instead of the description above I'm going to structure it like Git hooks:

~/.pomodoro
  current
  history
  settings
  hooks/
    start
    status
    finish

These can be anything executable.

I don't know if the hooks should 1-1 match subcommands, or if they should be logical events such as described above.

They will be passed some or all information about a pomodoro, still figuring out how to structure that data.

[facundoq]

This would be nice to add a notification sound/popup when the pomodoro finishes.

[justincampbell]

@facundoq I'd love that too, but it would require another service to be running and look for pomodoro status changes. I'd like to write a macOS menubar app soon (hopefully in Go?).

[jmburges]

One idea for making the finish actually get called when a pomodoro finishes is using the at command to schedule those things. I'm happy to try and make it happen.

[justincampbell]

@jmburges Interesting! Is there a way to edit/remove those commands if needed, such as if the user cancels a Pomodoro or finishes early?

I was thinking of relying on a separate process or GUI app (macOS menubar) that would implement the same interface /specification, and it could run hooks/play sounds/etc when the state changes. But then I suppose that's also an issue if you have multiple apps running, which one fires the hook?

I'll read more about at this week.

[jmburges]

Yeah I think both Mac and Linux have the command or can install very easily.

I’m playing around with a quick mock-up.

[vlcinsky]

hook for elapsed

I wanted to ring a bell when the time for planned pomodoro elapsed. This is how I use real timer when working pomodoro style - it triggers me to stop the pomodoro really and take a break.

Currently there is no event to hook a command for such event.

Even better hook would be to have an option to trigger the hook with short advance - e.g. 10 seconds. This would allow e.g. playing a sound, where ticking sound would warn me that the pomodoro is about to finish and finally would ring the bell.

Using current implementation of hooks is using pre-defined script names in the hooks directory. So the proposal would be to allow for script names such as:

• start: as today
• break: as today
• elapsed: act when planned pomodoro elapses
• elapsed-10s: act 10 seconds before the pomodoro elapses
• elapsed-1m: act 1 minute before the pomodoro elapses (this way we may support any duration defined after - character)
• stop

Anyway, simple elapsed hook would be very hany on it's own as is.

hook for pomodoro-elapsed and break-elapsed

We could extend the scenario for break too.

[sorribas]

Hi. I started using the tool today and I really like it. An idea to make this workflow work, at least for some people, is to add a new wait_end hook, and then for people who run pomodoro start --wait or pomodoro status --wait this could trigger the hooks without the need for another process. It obviously doesn't work if the user kills the wait, but it's just an idea.