Timetracker-csv

Pandas-friendly time tracking from the CLI, repo by repo

| |

┌────────────────────────────┐
│ 🕒 Timetracker CLI Tool    │
│ Track time → CSV → pandas  │
└────────────────────────────┘

Track time spent on multiple projects, one repo at a time from the CLI

Time is saved in pandas-friendly plaintext CSV files

timetracker

Description

Timetracker is a lightweight, privacy-respecting CLI tool that logs your work sessions into clean, pandas-friendly CSV files. Whether you're juggling multiple projects or just want a no-fuss way to monitor your productivity, Timetracker keeps your data local, editable, and analysis-ready. * No cloud. No surveillance. * Human-readable logs perfect for Python and pandas workflows. * Quick to set up, easy to use, and fully open source. * Supports free-form messages, optional activity types, and tag metadata

Quickstart

The username of the researcher running this timer is "bez." The project repository (repo) name is "meetinghouse."

#----------------------------------------------------
# 1) Initialize a timetracker project
$ cd /home/bez/projs/meetinghouse

$ trk init --csvdir doc/
or
$ trk init --d doc/
Initialized timetracker directory: /home/bez/projs/meetinghouse/.timetracker

#----------------------------------------------------
# 2) Start the timer
$ trk start
Timetracker started now: Mon 09:00 AM: 2025-03-24 09:00:00

Initializing with the option --csvdir doc/ (-d doc/) will cause time units to be written to a csv file stored in the doc/ directory, rather than in the default repo root directory.

#----------------------------------------------------
# 3) Stop the timer
$ trk stop -m 'Received instructions'
Timer stopped at Mon 2025-03-24 12:00:00 PM
Elapsed H:M:S 0:03:00 appended to doc/timetracker_meetinghouse_bez.csv

#----------------------------------------------------
# 4a) Report my time units for this project
$ trk report
Day  Date        Span     Total  Description
Sun  2025-03-24  03:00    03:00  Received instructions

#- - - - - - - - - - - - - - - - - - - - - - - - - - 
# 4b) Get my total hours spent on the project:
$ trk hours
0:03:00 H:M:S or 3.000 hours

Installation

Install with timetracker-csv pip:

$ pip install timetracker-csv

Or install from source:

$ git clone git@github.com:dvklopfenstein/timetracker.git
$ cd timetracker
$ pip install .