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 plain text CSV files.

• CSV files for each project can be combined into a single CSV file for analysis and plotting.

• Advantages
• Quickstart
• Installation
• Other time-trackers
• Documentation
• Issues and feedback

Advantages

• Freedom: Libre Software (aka open-source)
• Simple: Quick to set up
• Privacy: Own your data
• Anti-stalking: No invasive tracking ever of keystrokes, browser activity, mouse-clicks, etc., as is done by multitudinous other timetracking apps
• Human-and-machine-readable: ASCII data stored in CSV (comma-separated values) plaintext files:
  • Ready for pandas, the Python Data Analysis Library for tabular data
  • Editable using many editors, including vim and Notepad++
• Flexible: Modify your data if you forget to log time
• Quickview:
  • Current task being recorded
  • Elapsed time spent on the current task
• No clicking and clicking and clicking on a GUI
• Go off-line: No required use of the internet or cloud-based services
• Data field support: Data supported for each time interval includes:
  • A required free-form descriptive message
  • An optional activity or type
  • Any number of optional tags
• Plays nice: Export data for import by external time-tracking viewers

Quickstart

The name used by this time tracker is determined by the USER environmental variable by default.

1) Initialize a timetracker project

$ cd ~/projects/meetinghouse

$ trk init
Initialized timetracker directory: /home/bez/projects/meetinghouse/.timetracker

2) Start the timer

$ trk start
Timetracker started now: Mon 09:00 AM: 2025-03-24 09:00:00

3) Stop the timer

$ trk stop -m 'Received architectural plans'
Timer stopped at Mon 2025-03-24 12:00:00 PM
Elapsed H:M:S 0:03:00 appended to timetracker_meetinghouse_bez.csv

4) Report my time units for this project

$ trk report
Day  Date        Span     Total  Description
Sun  2025-03-24  03:00    03:00  Received architectural plans

You can also get the total hours that you spent on a project:

$ trk hours
0:03:00 H:M:S or 3.000 hours

Installation

Install with timetracker-csv pip:

$ pip install --upgrade timetracker-csv

Or install from source:

$ git clone [email protected]:dvklopfenstein/timetracker.git
$ cd timetracker
$ pip install .

Other timetrackers

• 700+ stars Bartib
• 740+ stars timetrace
• 13k stars ActivityWatch
• 85 stars ti
• 44 stars tim
• 6 stars Jupyter timetracker uses aTimeLogger CSV format
• https://atimelogger.pro/ CSV files
• List of timetrackers in PyPi
• web-based time tracking application
• Wage Labor record:
  • jupyter-timetracker - GUI too complex/too close to DB editing tools. No support for clients
  • tim CLI only, no idle time detection but uses hledger as a backend!
  • salary-timetracker CLI only, tracking bound to git repos, fixed hourly rate but hey it uses CSV files!
  • ttrac CLI only, no idle time detection, no support for clients or tasks but uses JSON files!
  • tickertock only with a StreamDeck, wants to use cloud service as backend but uses a hardware interface!
  • mttt CLI only, no idle time detection but uses plain text files!
  • tt-cli CLI only, no idle time detection, no support for clients
  • timetracker CLI only, no idle time detection, no support for clients
  • 1k stars hamster comes pretty close but seems outdated/abandoned and a little bit too complex

Copyright (C) 2025-present, DV Klopfenstein, PhD. All rights reserved