Cronometro: track study time from your terminal

Conceived and tested by Alessio Sferro, built by OpenAI GPT-5 through Codex. Alessio described the tool he needed and tested it himself; the AI assistant wrote the code.

Three hours at a desk can include a lot more than three hours of studying. Alessio wanted a simple way to record the time he actually spent working and keep track of each session’s goal.

Cronometro is the result: a small Python application that runs in the terminal and writes to a plain text file. You can read or edit the log with any text editor. It needs no third-party libraries or database.

Count the study time, pause for the rest

A phone call or a coffee break can make a study session look longer than it was. Cronometro keeps the session open while the timer is paused, then lets you resume where you left off. Study time and breaks are shown separately.

Use start to set a goal and begin a session. pausa pauses the timer and lets you add a reason; riprendi resumes it. Each break gets a start and end time automatically. stato shows the current session, and oggi shows today’s totals without stopping the timer. Commands also have English aliases.

Duration: 00:42:18 | Breaks: 00:05:31 | Status: paused
> resume

A log you can open anywhere

Each session keeps its starting time, focused duration, total breaks, ending time, goal and outcome. The table numbers each session and places its breaks in a separate block, showing start time, end time, duration and reason for every interruption. A dash appears when the reason is left blank, while the timing details remain available.

Monday 14 September 2026
========================
Session   | Start    | End      | Work     | Breaks
----------+----------+----------+----------+----------
        1 | 17:20:45 | 20:50:45 | 03:00:00 | 00:30:00
           Goal    : Complete the chapter
           Outcome : reached
           Breaks:
             # | Start    | End      | Duration | Reason
           ----+----------+----------+----------+------------------------------
             1 | 18:10:00 | 18:25:00 | 00:15:00 | Phone call
             2 | 19:30:00 | 19:45:00 | 00:15:00 | —

==========+==========+==========+==========+==========
Total     |          |          | 03:00:00 | 00:30:00

Goals reached:
  - Complete the chapter
Goals not reached:
  - None
Final summary: Chapter completed and notes reviewed.

With stop, the program asks whether the goal was reached, saves the session and stays open. With completa, it closes the day, calculates the totals, groups reached and missed goals, asks for an optional final summary and updates the file’s overall total.

The log doubles as a study journal. Session summaries show where the time went, while the break details help explain interruptions. New entries are added to the existing file, with no duplicate headings or totals.

Staying inside the terminal

Alessio already uses the terminal for exercises and projects. Keeping the timer there makes it easy to start or pause a session without switching to another app.

All it needs is Python 3.9 or newer and the path to the file where sessions should be saved:

python3 cronometro.py "$HOME/Documents/study.txt"

It can also be installed under ~/.local/bin and launched directly with the cronometro command. The main commands have short aliases and are available in both Italian and English.

Handling the less obvious cases

The project uses only Python’s standard library, but it handles several less obvious cases: multiple breaks in one session, multiple sessions on the same day, reopening completed days, recalculating overall totals and compatibility with data created by earlier versions.

OpenAI GPT-5 added automated tests through Codex for time calculations, goals, break reasons, formatting and totals. They also check that repeated sessions leave a readable log. With just a handful of commands, predictable behaviour matters.

Try it, read it, adapt it

Cronometro started with Alessio’s own study routine, but others may find it useful too. The code is available on GitHub under the MIT licence, so you can try it, see how it works and adapt it to your own habits.