⏰ temps

A free & open-source CLI time-tracking tool that allows you to make punch-clock entries for daily work time to keep track of overtime balances including functionality for showing stats and exporting Excel timesheets.
I built this very simple tool to accomodate my personal need for such a program and decided to share in case anyone else finds it useful.

Attributions

InquirerPy - DuckDB - pandas

Contents

• Limitations
• Changelog
• Requirements
• Installation
• How To Use

Limitations

This tool has certain limitations due to the way it was designed to accomodate my personal time-tracking needs, including the following:

• 1 entry per day (entries are timeboxed per day)
• No mixed entries (e.g. 4h work, 4h sick)
• No entries for future days
• Automatic break time deduction
• No support for previous overtime time balances
• Only 5 types of entries:
  • Work: Regular working day
  • Vacation: Vacation / PTO days
  • Public / Company Holiday: Country public holidays or days like Christmas or New Years where you might get PTO from your employer
  • Sick Leave: PTO during sickness
  • Overtime Compensation: Days taken off with the accrued overtime balance

Changelog

v1.0

• Initial release

Older Versions

No older versions available.

Requirements

• macOS Sequoia (tested for 15.X)
  • might work on other Unix-like operating systems but unconfirmed so far
• uv

Installation

After installing all hard requirements, the simplest way to get the script is to clone the repository and then install the required packages via a Python environment.

1. Clone the repository.

# Clone using web url
git clone https://github.com/maxschroen/temps.git
# OR clone using GitHub CLI
gh repo clone maxschroen/temps
# Navigate to project folder
cd temps

2. Install dependencies.

uv sync

How To Use

To run the script, simply navigate to the root of the repository after performing the installation steps and run:

# Navigate to project directory
cd <PATH/TO/GITHUB_REPO>/temps
# Run main.py file
uv run main.py

The script will give you prompts to walk you through the process.

Shortcut

In case you want to make the utility available via a one-word command, follow these instructions.

1. Create alias for application by pasting the following into your shell config (.zshrc, .bashrc, etc.)

alias temps='uv run --directory=<PATH/TO/GITHUB/REPO>/temps main.py' # replace with your own path

2. Quit and reopen your shell or set the shell config active via following command:

source <YOUR_SHELL_CONFIG> # replace with your own file path e.g. ~/.zshrc or ~/.bashrc