Usually
Usually is a command wrapper. You type usually make build where you would have typed make build. The command runs once, exactly as before: same output, same input, same exit code. The wrapper writes one line about the run in a plain text log. From the third finished run on, it tells you before the run how long that command usually takes in that directory. Afterwards it tells you whether this run was a usual one, gives the band it was judged by, and says how the band was made. Build it with go build -o usually . (Go 1.22 or newer, standard library only). Test it with go test ./... and sh test/e2e.sh, and replay the terminal sessions with sh test/tmux.sh edges or sh test/tmux.sh readme. Everything it reads is real: your own commands, the monotonic clock that times them, the wall clock that names the hour, and the log your runs have written (~/.usually.log, or the path in USUALLY_LOG). Everything it says goes to stderr, so a pipe on stdout carries only the command's bytes. To silence it, redirect stderr.
go build -o usually .
./usually make build
go vet ./... && go test ./... && sh test/e2e.sh
A real session
Below are six runs of sleep 61 in /tmp/proj with USUALLY_LOG=/tmp/proj/usually.log, on a small Linux machine whose clock keeps UTC, followed by the log. The text is pasted from tmux capture-pane -p, not typed, and the tab in each log line shows as spaces.
$ usually sleep 61
No record. This is the first.
$ usually sleep 61
From 1 run on record: 61 seconds. Too few to call anything usual.
$ usually sleep 61
From 2 runs on record: 61 seconds, 61 seconds. Too few to call anything usual.
$ usually sleep 61
Every one of the 3 runs took about 61 seconds.
That was a usual one.
Took 61 seconds. The usual band is 55 seconds to 67 seconds: the middle half of 3 runs, plus a tenth of the median.
$ usually sleep 61
Every one of the 4 runs took about 61 seconds.
That was a usual one.
Took 61 seconds. The usual band is 55 seconds to 67 seconds: the middle half of 4 runs, plus a tenth of the median.
$ usually sleep 61
Every one of the 5 runs took about 61 seconds.
Expect to finish at about half past nine in the morning. From 5 runs.
That was a usual one.
Took 61 seconds. The usual band is 55 seconds to 67 seconds: the middle half of 5 runs, plus a tenth of the median.
$ cat /tmp/proj/usually.log
Observations. One line per run. Durations in seconds, measured, not estimated.
Runs that did not finish with exit 0 are kept apart and not judged.
2026-10-13 09:26. Twenty-five past nine in the morning. 61.012 seconds, exit 0. In /tmp/proj sleep 61
2026-10-13 09:27. Half past nine in the morning. 61.001 seconds, exit 0. In /tmp/proj sleep 61
2026-10-13 09:28. Half past nine in the morning. 61.035 seconds, exit 0. In /tmp/proj sleep 61
2026-10-13 09:29. Half past nine in the morning. 61.001 seconds, exit 0. In /tmp/proj sleep 61
2026-10-13 09:30. Half past nine in the morning. 61.498 seconds, exit 0. In /tmp/proj sleep 61
2026-10-13 09:31. Half past nine in the morning. 61.013 seconds, exit 0. In /tmp/proj sleep 61
The rules
| finished runs on record | before the run | after the run |
|---|---|---|
| none | No record. This is the first., or how many failed runs are kept apart | nothing |
| 1 or 2 | their durations, then Too few to call anything usual. | nothing |
| 3 or more | Usually about ..., the shortest, the longest, and the count | the verdict and its evidence |
| 5 or more, with a median of a minute or more | also Expect to finish at about ... | the same |
- The same command means the same arguments in the same directory.
- Only the last 20 runs that ended with exit 0 are read. Other runs are written down, kept apart and never judged:
Exit 2. Kept apart, not judged. - The usual band is the middle half of the runs (25th to 75th percentile, nearest rank), widened on each side by a tenth of the median. The evidence line says so every time.
- When the runs fall into two clumps (a gap of at least double, with three runs on each side), it says
Runs come in two kindsand judges each run against its own kind. - A command whose median is under 2 seconds is not commented on. The hundredth finished run of a command is mentioned, once.
- Ctrl-C reaches the command. The wrapper records exit 130 and then dies by the same signal, so a shell loop stops.
- It never runs anything twice, never warms up, and has no flags beyond
-h.
The log
One line per run, appended when the command ends, under a lock, in a file created with mode 0600:
<YYYY-MM-DD HH:MM>. <the same time spoken>. <seconds, three decimals> seconds, exit <n>. In <directory><TAB><command>
Lines that do not have this shape are skipped and left alone, so the file can be read, grepped, corrected by hand or deleted. Deleting it is how a command forgets.
Colophon
Usually, catalogue number 7 of 100. One binary, one text file, no network, no colour. Set in your terminal's own typeface and printed on stderr. Durations are measured, not estimated, and times are spoken to the nearest five minutes, which is how people say them anyway. The usual it speaks of is manufactured on the premises, from at least three of your own runs and a tolerance of one tenth. The method is printed beside every judgement. It holds no opinion about runs that failed.
normal is dead