macusage reads the usage data MacOS already keeps about you and paints the last 30 days as a 24×30 heatmap: one column per day, one row per hour, each cell shaded by how long your screen was actually on.

It will not judge you for talking to Claude Code at 2 AM. 😈

No telemetry, no network, no dependencies. A single static binary that reads a local SQLite file and prints beautiful ansi blocks.

How it works

MacOS logs display activity in a SQLite database called knowledgeC.db. macusage opens it read-only, pulls every /display/isBacklit interval from the last 30 days, buckets the time into day/hour cells, and renders each cell as an ANSI true-color block — darker for idle hours, greener the longer the screen was on.

Requirements

• A terminal that supports true-color ansi
• MacOS (the knowledgeC.db database is MacOS-specific)

Getting started

Easiest is to just use macusage through npx:

npx macusage

[!NOTE] If you're hitting a permission denied, because macusage cannot access ~/Library/Application Support/Knowledge/knowledgeC.db, then you can use Finder to copy this .db file into a directory that macusage has access to, like your Downloads directory or /tmp. And then just run npx macusage $PATH_TO_DB_FILE

Getting started

Clone and build:

git clone https://github.com/gmegidish/macusage.git
cd macusage
make build

Then run it:

./macusage

That's it. By default it reads from ~/Library/Application Support/Knowledge/knowledgeC.db. Pass a different file if you have a copy of this file somewhere else.

Make targets

| Target | What it does | | ------------ | ------------------------------------- | | make build | Compile the macusage binary | | make run | Build and run in one step (go run .) | | make fmt | Format the source (go fmt) | | make vet | Run go vet | | make clean | Remove the built binary |

How to read it

• Columns are days, oldest on the left, today on the right. Date labels appear every 5 columns.
• Rows are hours of the day, 00 (midnight) at the top down to 23.
• Color is intensity: dark means the screen was off that hour, and the green deepens toward fully-on.

License

MIT