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 --- hooks/on_start | 52 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 16 deletions(-) (limited to 'hooks/on_start') diff --git a/hooks/on_start b/hooks/on_start index 441d6f1..fa38f7c 100755 --- a/hooks/on_start +++ b/hooks/on_start @@ -2,25 +2,45 @@ # ttym on_start -- runs when a session begins. # # $1 mode countdown | stopwatch -# $2 seconds requested duration for a countdown, 0 for a stopwatch +# $2 seconds requested duration of a countdown, 0 for a stopwatch # $3 comment the -c text, or an empty string # -# stdin, stdout and stderr are /dev/null: printing here goes nowhere and -# cannot corrupt the redrawn progress line. timer waits for this to exit, -# so keep it quick or background the slow part with &. +# Each hook works on its own: install only the ones you want. A hook that +# is missing or not executable is skipped silently. +# +# timer waits for this to exit, so keep it quick. stdout and stderr go to +# /dev/null -- printing here goes nowhere and cannot corrupt the progress +# line. To debug, run the hook by hand: +# +# ~/.config/ttym/hooks/on_start countdown 1500 "+work" mode=$1 seconds=$2 comment=$3 -# Name the terminal window after what is running. -case $TERM in -xterm*|rxvt*|tmux*|screen*|alacritty|foot*) - if [ "$mode" = countdown ]; then - printf '\033]0;timer %sm %s\007' "$((seconds / 60))" "$comment" > /dev/tty - else - printf '\033]0;stopwatch %s\007' "$comment" > /dev/tty - fi - ;; -esac +# --- session record ------------------------------------------------------ +# The log behind `timer -r` stores elapsed seconds only. It cannot tell a +# finished 25m from an abandoned 30m that ran 25m, because the duration +# you *asked for* is visible here and nowhere else. Pair this with the +# matching lines in on_done and on_quit to get intent versus outcome. +state=${XDG_STATE_HOME:-$HOME/.local/state}/ttym +if mkdir -p "$state" 2>/dev/null; then + printf '%s\tSTART\t%s\t%s\t%s\n' \ + "$(date +%Y-%m-%dT%H:%M:%S)" "$mode" "$seconds" "$comment" \ + >> "$state/sessions.tsv" +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 +# nothing restores these; recover with `dunstctl set-paused false`. +if [ "$mode" = countdown ]; then + command -v dunstctl > /dev/null 2>&1 && dunstctl set-paused true + command -v playerctl > /dev/null 2>&1 && playerctl pause 2>/dev/null + command -v mpc > /dev/null 2>&1 && mpc -q pause 2>/dev/null +fi + +# --- timewarrior --------------------------------------------------------- +# Turns -c comments into timew tags, so `timew summary :week +work` covers +# timer sessions alongside everything else you track. Uncomment to use. +# command -v timew > /dev/null 2>&1 && timew start ${comment:-timer} > /dev/null 2>&1 -# Pause music while a countdown runs (uncomment to use): -# [ "$mode" = countdown ] && playerctl pause 2>/dev/null +exit 0 -- cgit v1.3