From 9ba93a546018ef119f3b06812391d8baa57358be Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 25 Aug 2026 20:28:45 +0200 Subject: timer.1: document how to run hooks selectively Hooks are all-or-nothing per user: a file is installed or it is not, and there is no per-run flag. That the gate belongs inside the hook, and what it has to gate on, was only discoverable by reading the source. A hook inherits the environment timer was run with and is handed the -c comment as $3, so three gates are available: an environment variable for explicit opt-in, a +tag in the comment (free if you already pass -c, and still visible to timer --stats), or the session itself via $1 and $2 -- countdowns over ten minutes, say -- which needs nothing remembered. Also records the asymmetry that is easy to get wrong: gate on_start only. A hook that undoes something must run unconditionally in on_done and on_quit, or a session ending without the gate set leaves notifications paused or music stopped. Restore paths are harmless when there was nothing to restore. The shipped on_start now points at the new section, so the trick is visible from the file someone is already editing. Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP --- hooks/on_start | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'hooks/on_start') diff --git a/hooks/on_start b/hooks/on_start index fa38f7c..95b9377 100755 --- a/hooks/on_start +++ b/hooks/on_start @@ -30,7 +30,12 @@ fi # --- focus mode ---------------------------------------------------------- # Countdowns only: a stopwatch has no end, and silencing notifications -# indefinitely is not what you want. If the process is killed with -9 +# indefinitely is not what you want. To run this ad-hoc rather than on +# every countdown, gate it -- on an env var, on a +tag in $3, or on the +# duration in $2. See "Running hooks selectively" in timer(1). Gate here +# only, never in on_done/on_quit: those must always restore. +# +# [ -n "$TTYM_FOCUS" ] || exit 0 If the process is killed with -9 # nothing restores these; recover with `dunstctl set-paused false`. if [ "$mode" = countdown ]; then command -v dunstctl > /dev/null 2>&1 && dunstctl set-paused true -- cgit v1.3