Simple busy / idle time tracker inspired by the ancient article Inactivity and Idle Time on OS X.
According to the article, OS X has a timer called HIDIdleTime that tracks the last time you interacted with the computer, e.g. moved the mouse, typed a key, or interacted with the computer.
billy-idle simply queries this value periodically using the ioreg utility that ships with macOS, and matches it against a pre-defined threshold.
If exceeded, it will create a record for the busy time period in database.
This data can later be used as input for time tracking tools or statistics.
Friday January 10, 2025 (2025-01-10) Daily Report ---------------------------------------------------------------------------------------------------- 🕰 | TIME RANGE | 🐝 BUSY RECORD -----+---------------------+-------------------------------------------------------------------------------- ☕ | 08:42:52 → 11:55:07 | Spent 3h12m Driving a Pickup truck Mark Lt to Minneapolis #874 🌞 | 12:24:19 → 12:35:00 | Spent 10m Drinking a Belgian And French Ale Orval Trappist Ale with 2.6% #875 🌞 | 13:24:14 → 15:08:20 | Spent 1h44m Building App Tealgrammar 5.8.4 in Orc #876 🌞 | 15:09:27 → 15:24:27 | Spent 15m Driving a Van A4 Cabriolet to Orlando #877 🌞 | 15:24:27 → now | Still busy with Eating a Frozen kahlua creme topped with Clementine #878 -----+---------------------+-------------------------------------------------------------------------------- 🧮 | 5H23M +BREAK: 5H23M | BUSY+IDLE: 15H15M SKIP(<5M): 4 >REG(7H48M): -2H25M >MAX(10H): -4H37M -----+---------------------+-------------------------------------------------------------------------------- Suggestestion: 09:00 → 14:23 (inc. 0m break), you're expected to be busy for another 2h25m
CW | 📅 DATE | WEEKDAY | 🐝 BUSY | ⏲️ PLAN | 🕰 OVERTIME
-----+-------------+-----------+---------+----------+-------------
1 | 2025-01-01 | Wednesday | 0m | 0m | 0m
| 2025-01-02 | Thursday | 7h50m | 7h48m | 2m
| 2025-01-03 | Friday | 8h10m | | 22m
| | | | |
2 | 2025-01-06 | Monday | 9h | 7h48m | 1h12m
| 2025-01-07 | Tuesday | 8h50m | | 1h2m
| 2025-01-08 | Wednesday | 8h40m | | 52m
-----+-------------+-----------+---------+----------+-------------
TOTAL | 42H30M | 3H30M
| 6 DAYS | >39H
$ go run main.go
2024/10/01 17:13:29 🎬 billy started version=v0.0.2 built=2024-10-01T15:13:28Z pid=37477 go=go1.23.1 arch=arm64
2024/10/01 17:13:29 🥫 Open database file=~/.billy-idle/default/db.sqlite3 sqlite=3.46.0
2024/10/01 17:13:29 👀 Tracker started in idle mode with auto-idle>=2m0s interval=10s
2024/10/01 17:13:29 🐝 Enter busy mode after 0s idle time rec=#13
2024/10/01 17:15:33 💤 Checkpoint idleTime=11s state=idle lastSwitch=0s ago lastCheck=5s ago
2024/10/01 17:15:38 🛑 Received signal interrupt, initiate shutdown
2024/10/01 17:15:38 🛑 Tracker stopped after 0s busy time rec=#10
2024/10/01 17:15:38 🥫 Close database in ~/.billy-idle/dev|
Note
|
Binary packages for macOS amd64 and arm64 are coming soon, the same goes for docker images on ghcr.io |
Plist files in ~/Library/LaunchAgents/ are run at login with the id of the logged in user. See SO: launchctl and .plist file, Create and manage MacOS LaunchAgents using Go and Launching Custom Daemons Using launchd
$ cp com.github.tillkuhn.billy-idle.plist ~/Library/LaunchAgents
$ launchctl load ~/Library/LaunchAgents/com.github.tillkuhn.billy-idle.plist
$ launchctl start com.github.tillkuhn.billy-idle
# in case of Load failed: 5: Input/output error, try this first
$ launchctl unload ~/Library/LaunchAgents/com.github.tillkuhn.billy-idle.plistCLI Usage for track subcommand
Starts the tracker in daemon mode to record busy and idle times.
Usage:
billy-idle track [flags]
Flags:
-a, --app-root string App root Directory e.g. for SQLite DB (defaults to $HOME/.billy-idle (default "/Users/tillkuhn/.billy-idle")
-c, --cmd string Command to retrieve HIDIdleTime (default "ioreg")
--drop-create Drop and re-create db schema on startup
-e, --env string Environment (default "dev")
-h, --help help for track
-m, --idle duration Max tolerated idle time before client enters idle state (default 10s)
-i, --interval duration Interval to check for idle time (default 2s)
Global Flags:
-d, --debug Debug checkpointsCLI Usage for report subcommand
Generates a report based on the recorded idle and busy times.
Usage:
billy-idle report [flags]
Flags:
-a, --app-root string App Directory e.g. for SQLite DB (defaults to $HOME/.billy-idle/<env> (default "/Users/tillkuhn/.billy-idle")
-e, --env string Environment (default "default")
-h, --help help for report
--max-busy duration Max allowed time busy period per day (w/o breaks), report only (default 10h0m0s)
--min-busy duration Minimum time for a busy record to count for the report (default 5m0s)
--no-color Disable color output
--reg-busy duration Regular busy period per day (w/o breaks), report only (default 7h48m0s)
Global Flags:
-d, --debug Debug checkpointsCLI Usage for punch subcommand
Punch busy time
Usage:
billy-idle punch [flags]
Flags:
-h, --help help for punch
Global Flags:
-d, --debug Debug checkpointsBilly Idle currently only support a local sqlite database, more precisely modernc.org/sqlite which is a cgo-free port of SQLite.
But it shouldn’t be a big deal to add support for a remote PostgreSQL Database.
$ make
Usage: make <OPTIONS> ... <TARGETS>
Available targets are:
build build all targets
build-mac build for mac current arch using default goreleaser target path
clean Clean output directory
help Shows the help
install Install as launchd managed service
lint Lint go code
logs Show agent logs
minor Create Minor Release
release run goreleaser in snapshot mode
report Show report for default db
report-dev Show report for dev db
run Run app in tracker mode, add -drop-create to recreate db
run-help Run app in help mode
run-mac run mac build
test Run tests with coverage, implies lint
tidy Add missing and remove unused modules
update Update all go dependencies
Source: Wikimedia Commons, terms of the Free Art License apply.
If you want to contribute to rubin please have a look at the CONTRIBUTING.md