caledger: calendar + ledger-cli

Since August 2017, I’ve kept a ledger log for time tracking via timelog entries. As of December 1, 2024, I had over 7,500 time entries covering more than 16,000 logged hours (only 400 of those hours are not directly tied to work activities).

This started as a local text document that I updated throughout the workday as I changed tasks. Up until a few years ago it this wasn’t necessarily a timely activity; more often than not, the updates were appended at the end of the day (sometimes just before timesheets were due).

For some time I was relying on Drafts along with a custom syntax and some unpublished actions to help with time entry & reporting.

Recently, I decided to change up the “data” and syncing engine by using events on a dedicated iCloud calendar. Thanks to modern apps, local edits to this calendar are quickly synced with the cloud. As a bonus, I can use any calendar app as a gui for data entry tool (hello handy drag to move/resize event features).

Ledger demands plain text input and calendars are not plain text (and ICS exports are overly convoluted). Shortcuts provides all the component actions needed: read events from a specific calendar and iterate over those events to construct a properly-formatted ledger timelog. Since ledger is terminal-only, there was nothing holding me to pure shortcuts-based approach. So I made a cli app for pulling directly from iCloud and emitting a properly-formatted ledger timelog.

Ledger is great at quickly plowing through these data. The real friction point is adding the time entries. Up until now, the overwhelming majority of the entries in my timelog were manually entered though I had some Keyboard Maestro shortcuts to help with datetime stamps.