From 8543890f2e90af75a9bed7fa692ac92fc43285a4 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 25 Aug 2026 19:35:46 +0200 Subject: hooks: replace the examples with ones that do what the binary cannot The previous examples largely duplicated features of the patched build. on_done sent a desktop notification and played a sound, both of which the notify patch already does, so a user who copied it got two of each. on_quit recorded abandoned sessions, but the logging patch calls write_log() unconditionally at the end of every run: abandoned sessions were already in the log behind timer -r. The new set does two things nothing else can: - Intent versus outcome. The log stores elapsed seconds only, so a finished 25m and an abandoned 30m that ran 25m are indistinguishable in it. The duration actually requested is visible to on_start and nowhere else, so the examples write START/DONE/QUIT records to $XDG_STATE_HOME/ttym/sessions.tsv. - Focus mode. During a countdown, pause dunst notifications and any playerctl/mpc playback; restore on done or quit. Countdown only, so a stopwatch cannot silence notifications indefinitely. A timewarrior bridge is included but commented out. Two behaviours documented in the file comments, both read off the code rather than assumed: notify_and_sound() runs before the on_done hook, so with dunst paused the completion popup is queued and appears when the hook unpauses -- delayed, not lost; and nothing restores dunst if the process is killed with -9. Every external command is guarded with command -v, so the examples degrade to the session record alone on a machine without those tools. Each hook works standalone -- the man page and README now say so explicitly, since installing only on_quit is a normal setup. All three pass sh -n and shellcheck, and were tested across all three paths: completed countdown, abandoned countdown, stopped stopwatch, with dunstctl is-paused confirmed false afterwards. Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c85527c..e865c82 100644 --- a/README.md +++ b/README.md @@ -56,10 +56,13 @@ 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: +The three are independent -- installing only `on_quit` is a normal +setup. Three commented examples ship in `hooks/` and are installed to +`$(PREFIX)/share/doc/ttym/hooks/`. They record intent against outcome +(the duration you asked for is visible only to `on_start`, so the log +behind `timer -r` cannot show whether a session was cut short), and +run a focus mode that pauses dunst notifications and music during a +countdown. A commented timewarrior bridge is included: mkdir -p ~/.config/ttym/hooks cp /usr/local/share/doc/ttym/hooks/on_done ~/.config/ttym/hooks/ -- cgit v1.3