From f8a687cbb855ed4e3aa54128624101a21ba5a8c3 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 25 Aug 2026 19:19:14 +0200 Subject: hooks: ship three commented examples, install them, document the contract Add hooks/on_start, hooks/on_done and hooks/on_quit. They are named after the hooks themselves so copying one into ~/.config/ttym/hooks/ is the entire installation step, and each carries its argument contract in a header comment. on_start sets the terminal window title to what is running on_done desktop notification plus a sound, both backgrounded, with the first available of paplay/aplay/mpv/ffplay on_quit records abandoned sessions to a TSV under XDG_STATE_HOME and restores the terminal title make install places them in PREFIX/share/doc/ttym/hooks; make uninstall removes them and both directories; make dist ships hooks/ with the executable bits intact. The man page's HOOKS section now documents what the code actually does rather than what could be assumed from the call sites: - $2 differs per hook: requested duration on on_start, full duration on on_done, and time actually elapsed -- excluding time spent paused -- on on_quit. An abandoned 25m countdown reports what really ran. - $3 is always passed, so it is never unset. - hooks block: timer forks and waitpid()s, so on_done delays the completion bell and the alert loop. Background anything slow. - stdin, stdout and stderr all go to /dev/null, which is why printing is pointless and cannot corrupt the redrawn progress line. - execvp(3) means a script needs a #! line. README gains a Hooks section. All three examples pass sh -n and shellcheck, and were tested end to end through the documented flow: make install to a staging prefix, copy into a config dir, run. Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 5c0e3ea..c85527c 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,28 @@ Compile-time knobs live in config.def.h. On first build the Makefile copies it to config.h; edit config.h and re-`make` to change defaults. +Hooks +----- + +With the hooks patch applied, `timer` runs executables it finds at +`~/.config/ttym/hooks/{on_start,on_done,on_quit}`, each with three +arguments: mode (`countdown`/`stopwatch`), seconds, and the `-c` +comment. Dropping in an executable file is the only thing needed to +enable one. + +Three commented examples ship in `hooks/` and are installed to +`$(PREFIX)/share/doc/ttym/hooks/` -- terminal title, desktop +notification plus sound on completion, and a TSV record of abandoned +sessions: + + mkdir -p ~/.config/ttym/hooks + cp /usr/local/share/doc/ttym/hooks/on_done ~/.config/ttym/hooks/ + +Hooks run synchronously with stdout and stderr on /dev/null, so keep +them quick and write output to a file rather than the terminal. See +`man timer` for the full contract. + + Usage ----- -- cgit v1.3