whatbroke

README

whatbroke

It worked yesterday. What changed?

whatbroke answers that question for your Mac. It tracks everything installable (Homebrew, npm/pnpm globals, pip, pipx, mise, asdf, cargo), your dotfiles, your PATH, and macOS itself, then shows you what changed and when:

Real output from a first run, before any snapshot existed:

$ whatbroke since "10 days ago"
whatbroke: changes since 10 days ago (Sun Jun 21 15:27)

  installer  Command Line Tools for Xcode 26.6  + 26.6            Sun 00:35
  installer  Xcode                              + 26.6            Fri 01:11
  dotfile    ~/.zshrc                           modified          Jun 24
  brew       brotli                             1.1.0 → 1.2.0     Jun 24
  brew       hdf5                               1.14.6 → 2.1.1    Jun 24
  brew       boost                              1.89.0 → 1.90.0_1 Jun 24
  brew       tesseract                          5.5.1 → 5.5.2     Jun 24
  pip        pip [py3.14]                       → 26.1.2          Jun 24
  brew       python@3.14                        3.14.5 → 3.14.6   Jun 24
  brew       sqlite                             3.53.1 → 3.53.2   Jun 24
  ...

  forensics mode: no snapshots yet, reconstructed from filesystem timestamps
  (deletions and PATH changes are invisible without snapshots; run `whatbroke install`)
  this is what changed, not what's guilty. correlation, not blame

Install

Grab a prebuilt binary for macOS or Linux (arm64/amd64) from the releases page, or build from source with Go:

go install github.com/Dnakitare/whatbroke@latest
whatbroke install                       # daily snapshot via launchd (12:15 + on login)

A Homebrew tap is coming soon.

Usage

whatbroke                      # since yesterday
whatbroke since monday
whatbroke "3 days ago"
whatbroke 48h
whatbroke 2026-06-28
whatbroke --json since today   # machine-readable
whatbroke snapshot             # record a snapshot now
whatbroke status

How it works

Two modes, picked automatically:

Snapshot diff. A launchd job records a daily snapshot of everything observable (a few hundred items, one small JSON file) into ~/.local/share/whatbroke/. Asking since <when> diffs the right snapshot against the current state. This catches everything: upgrades, installs, removals, dotfile edits, PATH changes.

Forensics. No snapshot old enough? whatbroke reconstructs recent history from what the system already recorded: Homebrew install receipts, APFS directory birthtimes (npm sets file mtimes to a fake 1985 date, so birthtime is the honest signal), pip dist-info timestamps, and the macOS install history. Useful from the very first run, with stated limits: deletions and PATH edits are invisible without a prior snapshot.

Every run also quietly banks a snapshot (at most one per hour), so history starts accruing the moment you first use it, daemon or not.

Design notes

• Zero dependencies. Stdlib only, single static binary.
• Nothing leaves your machine. No network calls, no telemetry, ever.
• Honest output. The report says what changed, not which change broke you. It also tells you which mode produced it and what that mode can't see.
• Snapshots are plain JSON. Read them, back them up, delete them; whatbroke uninstall removes the daemon and keeps your data.

macOS only for now. The collectors are small and independent, so Linux support is mostly a matter of different paths.

License

MIT

Documentation

Overview

whatbroke answers "it worked yesterday, what changed on this machine?"

It diffs daily snapshots of everything installable (brew, npm, pip, mise, cargo, dotfiles, PATH, macOS) when it has them, and reconstructs recent history from filesystem timestamps when it doesn't.