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 written in Go
https://github.com/tillkuhn/billy-idle

go hours macos sqlite time-tracking timer tool work

Last synced: 12 days ago
JSON representation

💤 Billy Idle - Lightweight MacOS (In)activity Tracker written in Go

Host: GitHub
URL: https://github.com/tillkuhn/billy-idle
Owner: tillkuhn
License: apache-2.0
Created: 2024-09-27T14:24:58.000Z (3 months ago)
Default Branch: main
Last Pushed: 2024-12-10T19:12:26.000Z (22 days ago)
Last Synced: 2024-12-10T19:45:55.200Z (22 days ago)
Topics: go, hours, macos, sqlite, time-tracking, timer, tool, work
Language: Go
Homepage:
Size: 197 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.adoc
- Contributing: CONTRIBUTING.md
- License: LICENSE

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

----

Tuesday November 12, 2024 (2024-11-12) Daily Report

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

08:49:23 → 11:14:53: Spent 2h25m30s Building App Monkeydid 2.9.5 in CSP #306

11:27:51 → 11:38:52: Spent 11m1s Eating a Creamy apple dessert topped with Blackcurrant #307

11:40:40 → 12:33:24: Spent 52m44s Driving a Passenger car mini Pilot 4wd to Mesa #308

12:52:23 → 15:05:41: Spent 2h13m18s Driving a Passenger car medium Rio to Sacramento #309

16:05:28 → 16:27:43: Spent 22m15s Building App Darkorangerain 1.6.1 in F #311

16:27:43 → 16:58:49: Spent 31m6s Eating a Swirled cranberry cheesecake topped with Rock melon #312

17:20:02 → 18:51:29: Spent 1h31m27s Eating a Mexican rice pudding topped with Grape #313

19:07:32 → 19:33:40: Spent 26m8s Drinking a Light Hybrid Beer Stone IPA with 2.8% #317

19:52:25 → 20:35:48: Spent 43m23s Building App Jellyfishare 2.8.8 in WebDNA #318

20:52:23 → 21:02:20: Spent 9m57s Building App Troopcould 3.15.7 in Fancy #319

22:03:36 → now     : 🕰️  Still busy with Eating a A 1 cherry cobbler tart  a1 topped with Apricot #321

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

Total: 13h48m0s  busy: 10h0m0s  busy+break: 10h45m0s  skipped(<5m0s): 6  overMax(10h0m0s): false

Simple Entry for Tuesday: 09:00 → 19:45 (inc. 45m break)  overtime (>7h48m0s): 2h12m0s

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

----

== Run from 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

.CLI Usage for track subcommand

[source,shell]

----

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 checkpoints

----

.CLI Usage for report subcommand

[source,shell]

----

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/ (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 checkpoints

----

.CLI Usage for punch subcommand

[source,shell]

----

Punch busy time

Usage:

  billy-idle punch [flags]

Flags:

  -h, --help   help for punch

Global Flags:

  -d, --debug   Debug checkpoints

----

== 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[]