ttym - terminal countdown / stopwatch

A small countdown timer and stopwatch in C. Single binary, libc-only, no daemon. The base build is terminal-only -- it writes no files and spawns no processes:

T-24:13 +00:47 [████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  25%

countdown when given a duration; stopwatch when not
pause/resume with [space], quit with [q] or Ctrl+C
progress bar with eight styles (--bar, auto-detected by locale)
alert until keypress on completion (--no-persist to disable), with an optional reverse-video flash (--flash on|off)

Every feature that touches the filesystem, runs a subprocess or needs an external binary is an optional patch under patches/ -- desktop notifications, session logging, hooks and a runtime config file. See patches/README for the set and apply order.

Requirements

A C compiler and POSIX make. No external libraries.

Installation

Edit config.mk if needed, then:

make
sudo make install      # to $(PREFIX)/bin/timer ; default /usr/local

Override the prefix at build time:

make PREFIX=$HOME/.local install

The installed binary is named timer.

Configuration

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.

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/

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

timer [FLAGS] DURATION    countdown
timer [FLAGS]             stopwatch

DURATION:  25m | 90s | 2h | 1h30m | 01:30:00 | 25:00

FLAGS:
  -q              no sound
  -s              silent
  --no-persist    skip alert-until-keypress loop
  --flash on|off  terminal flash during alert loop
  --bar STYLE     bar style: unicode|ascii|hash|dots|line|block|arrow|minimal
  --              end of options
  -h              help

timer -h always reflects the build: each patch updates the help text in lockstep with the flags it adds.

License

MIT. See LICENSE.