track — a terminal time tracker

I have always used some sort of time tracking tool because it gives me insights I can use for time optimization. And now that I do consulting, it's also sometimes a requirement, e.g. for PyMC Labs clients I track my time with Toggl.

And I really like the Toggl UX. Click to start, click to stop. It's simple and it works. But it's also a service that costs money, and something about the simplicity of it made me want to replicate it, but making it even simpler.

So I built a dead simple terminal app to track the hours I spend working across clients and tasks. No GUI, no cloud, no database — just plain text files and a CLI that feels fast.

→ Get the code on GitHub

Install. Until it lands on PyPI, install directly from Git:

pip install "git+https://github.com/ulfaslak/track.git@main"

On first run the app asks where to store logs and remembers that in ~/.track_config. Each session is a tiny log file like YYYYMMDD-<n>---<client>---open.log which becomes ...---closed.log when you end it. Inside are four human-readable lines:

Task: <task>
Description: <description>
Start time: <YYYY-MM-DD HH:MM:SS>
End time: <YYYY-MM-DD HH:MM:SS>

Use. You can pass flags, but the fun part is the interactive flow with arrow-key pickers for client and task (and an optional description):

# start work (interactive)
track start

# start work (non-interactive)
track start -c acme -t modeling -d "feature engineering"

# resume the most recently closed task
track resume

# end an open session (choose if multiple are open)
track end

# see what's running right now
track status

# report hours for a client over a period
track report -c acme -p "today"
track report -c acme -p "this week"
track report -c acme -p "last month"

Reports. The report command aggregates hours by task and shows a clean summary. Periods include today and this/last week, month, quarter, year. It uses the log start time to decide which period a session belongs to.

Why text files? Because I want ownership and portability. Logs are readable, greppable, and versionable. If I ever move machines, well these are stored on my iCloud drive.

Under the hood it uses Typer for the CLI, Rich for pretty output, and Questionary for the arrow-key pickers.