Cronometro: measuring study without interrupting it

When I study, I do not only want to know how long I have been sitting at my desk. I want to understand how much focused work I have actually done, how many breaks I have taken and how that time is distributed throughout the day.

That need became Cronometro: a small terminal application written in Python. It requires no external libraries, uses no database and does not hide data in a proprietary format. Everything is recorded in a normal text file that I can open, move or edit whenever I want.

A simple but practical problem

A traditional timer measures passing time. During a study session, however, a phone call, a coffee or a longer break can significantly distort the result. I needed to pause the count without losing the session and to see focused time and break time separately.

The flow is deliberately simple: start begins a session, pausa pauses it and riprendi continues from the accumulated duration. The stato command shows the current values, while oggi totals everything recorded during the day without stopping the timer.

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

Choosing a text file

Each session keeps its starting time, focused duration, total breaks and ending time. The completa command closes the day, calculates its totals and updates the overall summary.

Monday 14 September 2026
========================
Start     | Duration | Breaks   | End
----------+----------+----------+---------
17:20:45  | 03:00:00 | 00:30:00 | 20:50:45
==========+==========+==========+=========
Total     | 03:00:00 | 00:30:00 |

I chose a readable format because the file is more than technical output: it is also a journal of study sessions. New records are appended without deleting existing content, and the program avoids duplicating headings and totals.

Staying inside the terminal

When I study, the terminal is already open for notes, exercises and projects. A lightweight command lets me start or pause without changing context or opening another interface.

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.

Small details that matter

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.

I added automated tests for break calculations, date and duration formatting, table structure and the absence of duplicate totals. It is a small project, but that is precisely what makes it a useful exercise: when the interface is reduced to a handful of commands, every behaviour needs to be predictable.

Why publish it

Cronometro was made for the way I study, but the problem is common. Publishing it makes the tool inspectable and adaptable for anyone who prefers simple, local and transparent software. The code is available on GitHub under the MIT licence.