Ktot

A simple, hotkeys-based time tracker

What's Ktot?

Ktot (Keep track of time) try to make time tracking much more convinient. Ktot is (for the most part) operated by using hotkey combinations

Features

• It's global:

  Which simply means that Ktot will work even if it's not focused. You need not Alt-Tab to the specific window and then click (or even worse, type) to start/stop the tracking. Just simply press the assigned hotkey from any window to get going

• Custom labels:

  You can define your own custom labels to track. You can add/remove as many labels as you want.

• Update existing labels:

  Name of existing labels can also be updated without losing their respective track log.

• Timestamps:

  By default, timestamps of the beginning and ending of each individual session of every label is recorded.

• Lable statistics:

  Ktot has built in option to show simple statistics of every label. It can show basic information like number of sessions, total session time, etc.

  

• Customizable hotkeys:

  The control hotkeys can be customized according to one's preference or to avoid conflict with existing hotkey combination.

Installation

git clone https://github.com/CodePleaseRun/ktot.git
cd ktot
python install.py

If the installation failed using python install.py, you can also manually install the packages using pip install

Windows:

• rich>=10.7.0
• click>=8.0.1
• keyboard>=0.13.5

Linux:

• rich>=10.7.0
• click>=8.0.1
• pynput>=1.7.3

Usage

Simply run the following command within the ktot/ directory:

python3 ktot.py

It will try to read existing session log from json/labels.json and load it. If it's your first time running the program then labels.json wiil be created in json/ & a prompt will ask to add a label.

The porgram is then controlled using hotkeys from deafult control scheme.

labels.json

All the sessions recorded are saved in labels.json as a single dictionary. Each label is saved as a key whose value is a single list. Each element of the list is another list of 3 elements (call it l1):

[beginning_timestamp, ending_timestamp, elapsed_time]

beginning_timestamp & ending_timestamp are saved as seconds since epoch. Each list (l1) represent a single session.

Options

There are 2 options (or flags) which can be toggled. For more info run:

python ktot.py --help

• By deafult, both starting and ending timestamps are saved as (begining_stamp, ending_stamp, elsapsed_time).

  --timestamp=False would save only elapsed_time and replaces both beginning_timestamp & ending_timestamp with -1 as [-1, -1, elapsed_time].

Custom Control Schemes

keyboard package is used for Windows and pynput is used for Linux. Both packages have different syntax for parsing the same hotkey combination. Thus, json/hotkeys.json contains a single combination written in 2 slightly different format, one for each package.

• Windows:

  keyboard parses both alphanumberic and special keys in same way. All keys are written in lowercase and separated by +.

  • Ctrl + Shift + Space is written as ctrl+shift+space
  • Ctrl + Alt + X is written as ctrl+alt+x

• Linux:

  pynput requires special keys to be enclosed under angle brackets < & >. Each key is separated by +

  • Ctrl + Shift + Space is written as <ctrl>+<shift>+<space>
  • Ctrl + Alt + X is written as <ctrl>+<alt>+x

Possible Future Updates

• Remapping controls to different hotkeys within the program
• Moving from json storage to a proper db. For a json file with 15 labels with 40k sessions each, average read and write time was 0.6 and 3.0 secs respectively

Licence

MIT