A Terminal Time Tracker

I wanted a small terminal utility that could tell me how long I had been working, so I could prepare a timesheet afterward. The basic interaction is simple: clock in, work, clock out. The less obvious part is keeping that session meaningful after the program closes or the date changes.

The time tracker began as an experiment separated into its own Visual Studio project in 2018. A later C++20 rewrite added an ncurses interface on Unix and revised the persistent clock-in/out logic. The current project story is that terminal rewrite and its unfinished edges.

A session at the keyboard

Space toggles the clock state. The display shows the current session and accumulated working time, along with amounts derived from an hourly rate entered in cents.

Those amounts are a convenience calculation from elapsed time and rate. The tool’s purpose is to help assemble the information for a timesheet; there is no completed payroll integration behind the display.

For a period I planned to connect the utility to the payroll system used for those timesheets. That remained planned work, separate from the terminal interaction and local log.

The log has to survive the process

The hours file stores dated clock pairs in time_log.csv in the process’s working directory. Loading the file reconstructs earlier entries and can resume an open session from the current day. The code also prevents opening a new date while the current record is still clocked in.

That puts persistence into the same state problem as the interface. Clocking out must update the stored record, and reopening the application must interpret that record consistently. A running timer alone would not preserve the information needed for the next timesheet.

Midnight changes the question

The main version appends a midnight split when a session crosses a day boundary. Development-branch revisions add new-day detection and move the previous daily minutes into accumulated past time before opening a new dated record.

The distinction matters when describing the implementation: the branches preserve different stages of the rollover work. Multi-day sessions remain unfinished, and daylight-saving changes, clock adjustments and concurrent access to the log have not been established as supported behavior.

A GCC 16 build of both later branches configures successfully but stops at an overload conflict in the older date dependency, before the application can be exercised. The surviving implementation still gives a concrete account of the work: terminal interaction, persisted session state and the calendar boundaries that make a small time tracker more involved than a stopwatch.