Itemised

Itemised is a command wrapper: type itemised in front of any command, the command runs exactly as it would have (its own output, colours, prompts, signals and exit code), and afterwards a 48 column till receipt goes to stderr listing every file the command created, changed and removed in the working directory, with exact byte totals, the exit code, the elapsed time, the free space on the volume before and after, and a plain list of what it did not look at, ending in the net as Amount due when the command used space or Change due when it gave space back. It needs Python 3.11 or later and nothing else: from this folder, uv run itemised.py bun run build (or ./itemised.py ..., whose shebang is uv run --script; put a symlink named itemised on your PATH to type it as itemised ...). Its real input is your own working directory and whatever command you give it: the real clock, lstat of real files, and the real free space of the volume. No sample data ships with it.

Usage

itemised [--also PATH]... [--full] [--limit N] [--] COMMAND [ARGS...]

A shell string is itemised sh -c '...'. A command that cannot be started prints one line (itemised: not found: NAME) and exits 127 with no receipt. Ctrl-C reaches the command as usual; the receipt still prints and the exit is 130. The receipt is on cream paper (#FCF0DD, ink #1A1A1A) only when stderr is a terminal, NO_COLOR is unset and COLORTERM is truecolor or 24bit; otherwise it is plain text with no escape bytes.

A real receipt

From the acceptance run on the Linux build box, itemised wrapped around this folder's own test suite, in a fresh copy under the system temp directory. An independent find and stat sum of the tree before and after gave 29,989 and 87,321 bytes: a difference of 57,332, the net line to the byte.

                    itemised
                 normal is dead
================================================
2026-10-13 14:33:26                 No. DC6FC832
Served by: uv
uv run python -m unittest -q
in /tmp/tmp.iFeDhxUdiY/c10/itemised
================================================
CREATED
__pycache__/itemised.cpython-312.pyc    +34.5 kB
__pycache__/test_itemised.cpython-312.pyc
                                        +22.8 kB
================================================
created      2 files                   +57,332 B
changed      0 files                         0 B
removed      0 files                         0 B
net                                    +57,332 B
exit 0  1.6 s                     counting 0.0 s
volume free      95.15 GB before, 95.14 GB after
================================================
Not examined: made and removed during the run
Not examined: file contents, only size and times
Not examined: outside the working directory
================================================
Amount due                               57.3 kB

What it does not see

Measured: bun install, then rm -rf node_modules

In a throwaway project under the system temp directory with a real bun.lock for vite and typescript and a populated bun cache (bun 1.4.3, run with --offline):

Checks

uv run python -m unittest -q
bash acceptance.sh > out/acceptance.txt
uv run python shots.py

test_itemised.py covers the pure parts and a few real runs. acceptance.sh runs acceptance checks 2 to 11 of CARD.md for real in throwaway directories (it needs Linux with GNU tools, tmux, git and a warm bun cache) and leaves the real tmux captures in out/; shots.py turns those captures into the pages photographed in shots/. BUILD.md records each check and its output.

Colophon

Itemised, catalogue number 23 of 100. One file of Python standard library. Set in the terminal's own monospace on paper the terminal does not have, 48 columns, one ink. Every figure was measured at the counter. All amounts are in bytes. Keep this slip for your records, or do not.

Files