<p align="center" style="display:inline">
<h1 align="center">Timetracker-csv</h1>
<h3 align="center">Pandas-friendly time tracking from the CLI, repo by repo</h3>
<h3 align="center">
<a href="https://pypi.org/project/timetracker-csv"><img src="https://img.shields.io/pypi/v/timetracker-csv" alt="PyPI - Version"></a> |
<a href="https://doi.org/10.5281/zenodo.14803226"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.14803226.svg" alt="DOI"></a> |
<a href="https://www.gnu.org/licenses/agpl-3.0.en.html"><img src="https://img.shields.io/github/license/dvklopfenstein/timetracker" alt="License"></a>
</h3>
<pre align="center" style="font-family: monospace; font-size: larger; border: 1px solid #ccc; padding: 10px; display: inline-block;">
┌────────────────────────────┐
│ 🕒 Timetracker CLI Tool │
│ Track time → CSV → pandas │
└────────────────────────────┘
</pre>
</p>
---
* Track time spent on multiple projects,
one repo at a time from the [CLI](https://blog.iron.io/pros-and-cons-of-a-command-line-interface)
* Time is saved in
[pandas](https://pandas.pydata.org/pandas-docs/stable/index.html)-friendly
plain text [CSV](https://www.datarisy.com/blog/understanding-csv-files-use-cases-benefits-and-limitations) files.
* CSV files for each project can be combined into a single CSV file for analysis and plotting.
<p align="center"><img src="https://github.com/dvklopfenstein/timetracker/raw/main/doc/mkdocs/source/images/stopwatch.png" alt="timetracker" width="750"/></p>
* [Advantages](#advantages)
* [Quickstart](#quickstart)
* [Installation](#installation)
* [Other time-trackers](#other-timetrackers)
* [Documentation](http:/dvklopfenstein.github.io/timetracker)
* [Issues and feedback](https://github.com/dvklopfenstein/timetracker/issues/new/choose)
## 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](http://www.markwk.com/plain-text-life.html) files:
* Ready for [pandas](https://pandas.pydata.org/), the Python Data Analysis Library for tabular data
* Editable using [many editors](https://survey.stackoverflow.co/2024/technology/#3-integrated-development-environment), 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 `tag`s
* **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](https://pypi.org/project/timetracker-csv/) pip:
```
$ pip install timetracker-csv
```
Or install from source:
```
$ git clone git@github.com:dvklopfenstein/timetracker.git
$ cd timetracker
$ pip install .
```
## Other timetrackers
* 700+ stars [Bartib](https://github.com/nikolassv/bartib)
* 740+ stars [timetrace](https://github.com/dominikbraun/timetrace)
* 13k stars [ActivityWatch](https://github.com/ActivityWatch/activitywatch)
* 85 stars [ti](https://github.com/richmeta/ti)
* 44 stars [tim](https://github.com/MatthiasKauer/tim)
* 6 stars [Jupyter timetracker](https://github.com/PrateekKumarPython/jupyter-timetracker) uses aTimeLogger CSV format
* https://atimelogger.pro/ CSV files
* [List of timetrackers in PyPi](https://pypi.org/search/?q=timetracker)
* [web-based time tracking application](https://github.com/anuko/timetracker)
* [Wage Labor record](https://pypi.org/project/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](https://github.com/projecthamster/hamster)
Copyright (C) 2025-present, DV Klopfenstein, PhD. All rights reserved
Raw data
{
"_id": null,
"home_page": null,
"name": "timetracker-csv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Linux, cli, productivity, csv, history, collaboration, pandas, time-tracker, timetracker, csv-reading, csv-export, timetracking",
"author": null,
"author_email": "\"DV Klopfenstein, PhD\" <dvklopfenstein@protonmail.com>",
"download_url": null,
"platform": null,
"description": "<p align=\"center\" style=\"display:inline\">\n<h1 align=\"center\">Timetracker-csv</h1>\n<h3 align=\"center\">Pandas-friendly time tracking from the CLI, repo by repo</h3>\n<h3 align=\"center\">\n<a href=\"https://pypi.org/project/timetracker-csv\"><img src=\"https://img.shields.io/pypi/v/timetracker-csv\" alt=\"PyPI - Version\"></a> |\n<a href=\"https://doi.org/10.5281/zenodo.14803226\"><img src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.14803226.svg\" alt=\"DOI\"></a> |\n<a href=\"https://www.gnu.org/licenses/agpl-3.0.en.html\"><img src=\"https://img.shields.io/github/license/dvklopfenstein/timetracker\" alt=\"License\"></a>\n</h3>\n<pre align=\"center\" style=\"font-family: monospace; font-size: larger; border: 1px solid #ccc; padding: 10px; display: inline-block;\">\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \ud83d\udd52 Timetracker CLI Tool \u2502\n\u2502 Track time \u2192 CSV \u2192 pandas \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</pre>\n</p>\n\n---\n\n* Track time spent on multiple projects,\none repo at a time from the [CLI](https://blog.iron.io/pros-and-cons-of-a-command-line-interface) \n\n* Time is saved in\n[pandas](https://pandas.pydata.org/pandas-docs/stable/index.html)-friendly\nplain text [CSV](https://www.datarisy.com/blog/understanding-csv-files-use-cases-benefits-and-limitations) files.\n\n* CSV files for each project can be combined into a single CSV file for analysis and plotting.\n\n<p align=\"center\"><img src=\"https://github.com/dvklopfenstein/timetracker/raw/main/doc/mkdocs/source/images/stopwatch.png\" alt=\"timetracker\" width=\"750\"/></p>\n\n* [Advantages](#advantages)\n* [Quickstart](#quickstart)\n* [Installation](#installation)\n* [Other time-trackers](#other-timetrackers)\n* [Documentation](http:/dvklopfenstein.github.io/timetracker)\n* [Issues and feedback](https://github.com/dvklopfenstein/timetracker/issues/new/choose)\n\n## Advantages\n* **Freedom**: Libre Software (aka open-source)\n* **Simple**: Quick to set up\n* **Privacy**: Own your data\n* **Anti-stalking**: No invasive tracking ever of keystrokes, browser activity, mouse-clicks, etc.,\nas is done by multitudinous other timetracking apps\n* **Human-and-machine-readable**: ASCII data stored in CSV (comma-separated values) [plaintext](http://www.markwk.com/plain-text-life.html) files:\n * Ready for [pandas](https://pandas.pydata.org/), the Python Data Analysis Library for tabular data\n * Editable using [many editors](https://survey.stackoverflow.co/2024/technology/#3-integrated-development-environment), including vim and Notepad++\n* **Flexible**: Modify your data if you forget to log time\n* **Quickview**:\n * Current task being recorded\n * Elapsed time spent on the current task\n* **No clicking and clicking and clicking** on a GUI\n* **Go off-line**: No required use of the internet or cloud-based services\n* **Data field support**: Data supported for each time interval includes:\n * A required free-form descriptive message\n * An optional `activity` or type\n * Any number of optional `tag`s\n* **Plays nice**: Export data for import by external time-tracking viewers\n\n## Quickstart\nThe `name` used by this time tracker is determined by the `USER` environmental variable by default.\n### 1) Initialize a timetracker project\n```\n$ cd ~/projects/meetinghouse\n\n$ trk init\nInitialized timetracker directory: /home/bez/projects/meetinghouse/.timetracker\n```\n### 2) Start the timer\n```\n$ trk start\nTimetracker started now: Mon 09:00 AM: 2025-03-24 09:00:00\n```\n### 3) Stop the timer\n```\n$ trk stop -m 'Received architectural plans'\nTimer stopped at Mon 2025-03-24 12:00:00 PM\nElapsed H:M:S 0:03:00 appended to timetracker_meetinghouse_bez.csv\n```\n### 4) Report my time units for this project\n```\n$ trk report\nDay Date Span Total Description\nSun 2025-03-24 03:00 03:00 Received architectural plans\n```\nYou can also get the total hours that you spent on a project:\n```\n$ trk hours\n0:03:00 H:M:S or 3.000 hours\n```\n\n## Installation\nInstall with [timetracker-csv](https://pypi.org/project/timetracker-csv/) pip:\n```\n$ pip install timetracker-csv\n```\nOr install from source:\n```\n$ git clone git@github.com:dvklopfenstein/timetracker.git\n$ cd timetracker\n$ pip install .\n```\n\n## Other timetrackers\n* 700+ stars [Bartib](https://github.com/nikolassv/bartib)\n* 740+ stars [timetrace](https://github.com/dominikbraun/timetrace)\n* 13k stars [ActivityWatch](https://github.com/ActivityWatch/activitywatch)\n* 85 stars [ti](https://github.com/richmeta/ti)\n* 44 stars [tim](https://github.com/MatthiasKauer/tim)\n* 6 stars [Jupyter timetracker](https://github.com/PrateekKumarPython/jupyter-timetracker) uses aTimeLogger CSV format\n* https://atimelogger.pro/ CSV files\n* [List of timetrackers in PyPi](https://pypi.org/search/?q=timetracker)\n* [web-based time tracking application](https://github.com/anuko/timetracker)\n* [Wage Labor record](https://pypi.org/project/wage-labor-record/):\n * jupyter-timetracker - GUI too complex/too close to DB editing tools. No support for clients\n * tim CLI only, no idle time detection but uses hledger as a backend!\n * salary-timetracker CLI only, tracking bound to git repos, fixed hourly rate but hey it uses CSV files!\n * ttrac CLI only, no idle time detection, no support for clients or tasks but uses JSON files!\n * tickertock only with a StreamDeck, wants to use cloud service as backend but uses a hardware interface!\n * mttt CLI only, no idle time detection but uses plain text files!\n * tt-cli CLI only, no idle time detection, no support for clients\n * timetracker CLI only, no idle time detection, no support for clients\n * 1k stars [hamster comes pretty close but seems outdated/abandoned and a little bit too complex](https://github.com/projecthamster/hamster)\n\nCopyright (C) 2025-present, DV Klopfenstein, PhD. All rights reserved\n",
"bugtrack_url": null,
"license": null,
"summary": "Pandas-friendly time tracking from the CLI",
"version": "0.8.4",
"project_urls": {
"Changelog": "https://github.com/dvklopfenstein/timetracker/blob/main/CHANGELOG.md",
"Documentation": "https://dvklopfenstein.github.io/timetracker/",
"Homepage": "https://github.com/dvklopfenstein/timetracker",
"Issues": "https://github.com/dvklopfenstein/timetracker/issues",
"PiPy": "https://pypi.org/project/timetracker-csv/"
},
"split_keywords": [
"linux",
" cli",
" productivity",
" csv",
" history",
" collaboration",
" pandas",
" time-tracker",
" timetracker",
" csv-reading",
" csv-export",
" timetracking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "67f60fee594f4691d85bb7df65070c02ae710e47eeb1dd5818bc9d12295a610c",
"md5": "8c367594496c03117f502ba035739a68",
"sha256": "ec049e3b78922c0d5fb8dacff9b9d054f0cb787b1fa2b4b8587bf703ae59395e"
},
"downloads": -1,
"filename": "timetracker_csv-0.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c367594496c03117f502ba035739a68",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 75462,
"upload_time": "2025-07-15T18:16:27",
"upload_time_iso_8601": "2025-07-15T18:16:27.312144Z",
"url": "https://files.pythonhosted.org/packages/67/f6/0fee594f4691d85bb7df65070c02ae710e47eeb1dd5818bc9d12295a610c/timetracker_csv-0.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 18:16:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dvklopfenstein",
"github_project": "timetracker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "timetracker-csv"
}
JSON
