Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tillkuhn/billy-idle

💤 Billy Idle - Lightweight MacOS (In)activity Tracker
https://github.com/tillkuhn/billy-idle

go hours macos sqlite time-tracking timer tool work

Last synced: 15 days ago
JSON representation

💤 Billy Idle - Lightweight MacOS (In)activity Tracker

Awesome Lists containing this project

README 

        
image:https://github.com/tillkuhn/billy-idle/actions/workflows/go.yml/badge.svg[ci-build]



== 💤 Billy Idle - Lightweight macOS (In)activity Tracker



Simple busy / idle time tracker inspired by the ancient article https://www.dssw.co.uk/blog/2015-01-21-inactivity-and-idle-time/[Inactivity and Idle Time on OS X].



== Background



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.



== Example Time Tracking Report



----

2024-10-08 Tue 08:46:55 #131 Spent 1h24m21s Building App Beetlecan 3.7.17 in Prolog until 10:11AM

2024-10-08 Tue 11:09:36 #132 Spent 32m12s Eating a Islands bananas foster topped with Gooseberry until 11:41AM

2024-10-08 Tue 11:41:49 #133 Spent 1h11m45s Driving a Sport utility vehicle Grand Marquis to Virginia Beach until 12:53PM

2024-10-08 Tue 12:59:47 #134 Spent 11m21s Building App Cigarettebe 4.13.19 in JOSS until 1:11PM

2024-10-08 Tue 13:32:02 #135 Spent 1h46m51s Driving a Passenger car medium C1500 Yukon 2wd to Glendale until 3:18PM

2024-10-08 Tue 15:30:33 #136 Spent 1h56m28s Eating a Chocolate almond roca bar topped with Cherry until 5:27PM

2024-10-08 Tue 17:30:30 #137 Spent 11m41s Driving a Passenger car compact Bentley Arnage to Hialeah until 5:42PM

2024-10-08 Tue 18:39:54 #138 Spent 1h19m44s Driving a Passenger car heavy Escalade Esv Awd to Louisville/Jefferson until 7:59PM

2024-10-08 Tue 19:59:58 #139 Spent 43m43s Driving a Van M3 Convertible to Reno until 8:43PM

----------------------------------------------------------------------------------------------------

total: 20h46m0s  busy: 9h18m0s  busy+break: 10h3m0s  skipped(<5m0s): 12  belowMax(10h0m0s): true

Simple Entry for Tuesday: 09:00 → 19:03 (inc. 45m break) overtime: 1h30m0s

====================================================================================================

----

----

2024-10-10 Thu 03:05:53 #157 Spent 48m27s Drinking a Fruit Beer Péché Mortel with 6.6% until 3:54AM

2024-10-10 Thu 08:54:09 #158 Spent 4h2m30s Building App Dollarjump 2.11.6 in Napier88 until 12:56PM

2024-10-10 Thu 13:17:21 #159 Spent 3h59m22s Eating a Sonic strawberry cheesecake shake topped with Huckleberry until 5:16PM

2024-10-10 Thu 17:17:44 #160 🕰️  Still busy with Building App SkyBlueline 5.14.18 in Elixir since 49m50s

----------------------------------------------------------------------------------------------------

total: 17h48m0s  busy: 9h40m0s  busy+break: 10h25m0s  skipped(<5m0s): 3  belowMax(10h0m0s): true

Simple Entry for Thursday: 09:00 → 19:25 (inc. 45m break) overtime: 1h52m0s

====================================================================================================

----



== Run form source



[source,shell]

----

$ 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



== Install as launchd managed service (experimental)



Plist files in ~/Library/LaunchAgents/ are run at login with the id of the logged in user.

See https://stackoverflow.com/a/13372744/4292075[SO: launchctl and .plist file],

https://ieftimov.com/posts/create-manage-macos-launchd-agents-golang/[Create and manage MacOS LaunchAgents using Go]

and  https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html#//apple_ref/doc/uid/10000172i-SW7-BCIEDDBJ[Launching Custom Daemons Using launchd]



[source,shell]

----

$ 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.plist

----



== CLI Arguments



[source,shell]

----

$ billy help



Usage: billy [command]



Available Commands (more coming soon):

  track    Starts the tracker



Use "billy [command] -h" for more information about a command.

----



[source,shell]

----

$ billy track -help



Usage of track:

  -app-dir string

    	App Directory e.g. for SQLite DB (defaults to $HOME/.billy-idle/

  -cmd string

    	Command to retrieve HIDIdleTime (default "ioreg")

  -debug

    	Debug checkpoints

  -drop-create

    	Drop and re-create db schema on startup

  -env string

    	Environment (default "default")

  -idle duration

    	Max tolerated idle time before client enters idle state (default 10s)

  -interval duration

    	Interval to check for idle time (default 2s)

  -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)

  -reg-busy duration

    	Regular busy period per day (w/o breaks), report only (default 7h48m0s)

----



== Database Support



*Billy Idle* currently only support a local https://gitlab.com/cznic/sqlite[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 https://www.postgresql.org[PostgreSQL] Database.



image:docs/sqlite.png[]



== Development



[source,shell]

----

$ make

Usage: make  ... 



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

----



== 🎸 Credits



image:https://upload.wikimedia.org/wikipedia/commons/thumb/7/74/Billy_idol_ill_artlibre_jnl.png/640px-Billy_idol_ill_artlibre_jnl.png[]



Source: https://commons.wikimedia.org/wiki/File:Billy_idol_ill_artlibre_jnl.png[Wikimedia Commons], terms of the https://en.wikipedia.org/wiki/en:Free_Art_License[Free Art License] apply.



== Contribution



If you want to contribute to *rubin* please have a look at the xref:CONTRIBUTING.md[]