Git-Chronos
Git-Chronos is a standalone command-line utility (CLI) written in Python that automatically tracks working time and calculates earnings based on the commit history of local Git repositories.
The tool is designed for freelancers and contract developers. It runs 100% locally, guarantees full data privacy, and requires no internet connection or third-party AI services.
Features
- Automatic time tracking — derives billable hours from your Git commit history; no manual timers.
- Earnings calculation — multiplies tracked hours by your hourly rate and produces a total amount due.
- Session-aware algorithm — groups commits into work sessions with configurable gap thresholds and start buffers.
- Task parsing — attributes session time to tasks when commit messages follow a pattern like
TASK-123:orfeature:. - Beautiful terminal reports — a colored TUI dashboard built with Rich.
- Corporate-grade Excel invoices — styled
.xlsxreports generated withopenpyxl, including native ExcelSUMformulas. - Private by design — everything runs locally; no data ever leaves your machine.
Project Structure
git-chronos/
│
├── git_chronos/ # Main source package
│ ├── __init__.py
│ ├── cli.py # Command-line interface (Typer)
│ ├── config.py # config.toml initialization and reading
│ ├── git_parser.py # Git history module (GitPython)
│ ├── analyzer.py # Time-calculation engine
│ └── exporters/ # Report exporters
│ ├── __init__.py
│ ├── excel.py # Designer Excel reports (openpyxl)
│ └── terminal.py # Colored TUI dashboard (Rich)
│
├── pyproject.toml # Package dependencies and metadata
├── README.md # Repository documentation
└── LICENSE # MIT License
Installation
Python 3.10+ is required.
pip install git-chronos
Or straight from GitHub:
pip install git+https://github.com/KokosP/git-chronos
Or install from source:
git clone https://github.com/KokosP/git-chronos
cd git-chronos
pip install .
Configuration
On first run, or via the git-chronos init command, a .git-chronos.toml file is created in the user's home directory.
Config file structure
[developer]
name = "Ivan Ivanov"
email = "ivan@developer.dev" # Filter: only count commits by this author
[finance]
currency = "USD" # ISO code: USD, EUR, GBP, RUB, ...
hourly_rate = 25.0 # Hourly rate (price per 1 hour)
[algorithm]
session_gap_hours = 2.0 # Max. break between commits (in hours)
first_commit_buffer_mins = 30 # "Warm-up" time before the first commit of the day
[reporting]
company_name = "Freelance Inc."
client_name = "Best Customer LLC"
CLI Commands
The interface is built on Typer.
| Command | Description |
|---|---|
git-chronos init |
Creates the default .git-chronos.toml config file |
git-chronos status |
Validates the config and prints the current rate |
git-chronos analyze [PATH] |
Analyzes the repository at the given path (default: .) |
analyze options
--period— reporting period:week,month, orcustom--export— output format:terminal,excel, orboth--since/--until— date boundsYYYY-MM-DD(required for--period custom)--currency— override the currency for this run (e.g.USD,EUR,GBP)--rate— override the hourly rate for this run--all— count commits across all branches and tags, not only the current branch (HEAD)
Examples
git-chronos init
git-chronos status
git-chronos analyze .
git-chronos analyze ~/projects/client-app --period month --export both
git-chronos analyze . --currency EUR --rate 40
Time-Calculation Algorithm
Commits are extracted from the local .git folder via GitPython and filtered by developer.email.
- Grouping — all commits are sorted chronologically and grouped by day.
- Session detection — if the gap between commit A and commit B is less than
session_gap_hours(e.g., 2 hours), the interval is treated as continuous work, andTime(B) - Time(A)is added to the day's timer. - Breaks — if the gap exceeds
session_gap_hours, the current session is closed. The idle interval is treated as rest and is not billable. - Start buffer —
first_commit_buffer_mins(e.g., 30 minutes) is added before the first commit of each new session (or the first commit of the day), since code is written before it is committed. - Task parsing — if a commit message starts with a task pattern (e.g.,
TASK-123:orfeature:), the session's time is attributed to that task.
Output Design
Terminal dashboard (exporters/terminal.py)
Using Rich, the utility renders a formatted report card:
- Header — a gradient-framed panel with the utility name and metadata (Developer / Client).
- Finance block — a brightly highlighted block (e.g., green for income):
Total due: 80.5 h × $25.00 = $2,012.50 - Activity charts — pseudo-graphic bars via
Rich.progressor█characters visualizing load by day or week.
Excel invoice (exporters/excel.py)
The .xlsx file is generated via openpyxl and follows modern corporate design rules:
- Color palette — no default styles. Slate Gray (
#34495E) table headers with white text; alternating data rows with a light gray tint for readability. - Formatting — date columns use
YYYY-MM-DD, hour columns use0.0, money columns use a strict financial format (e.g.,$#,##0.00). - Formulas — totals in money and hours are computed with native Excel formulas (
=SUM(...)), not hardcoded text.
Tech Stack
| Library | Purpose |
|---|---|
typer |
Command-line interface (CLI) |
gitpython |
Low-level reading of local Git repository history |
toml |
Parsing and validating the config file |
rich |
Terminal formatting: tables, colors, charts |
openpyxl |
Generating and styling Excel reports |
Constraints: Python 3.10+. No external APIs or AI models are used.
License
This project is licensed under the MIT License.
Copyright (c) sbgid.com
Metadata
Release files for git-chronos 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| git_chronos-0.1.0.tar.gz | 16.2 kB | Without provenance | Details for git_chronos-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| git_chronos-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for git_chronos-0.1.0-py3-none-any.whl |
Total release size: 32.0 kB
Release files / git_chronos-0.1.0.tar.gz
| Download URL | git_chronos-0.1.0.tar.gz |
|---|---|
| Size | 16.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d698061b869309d08eecf300a9f612f466a9c9d9be596e288a97c0a9491e47d
|
|
BLAKE2b-256 checksum How to use checksums |
225cd1ed41f0ed8f61a34601eb162b4fe40dddaff50ba0851448c3af5475e4a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / git_chronos-0.1.0-py3-none-any.whl
| Download URL | git_chronos-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4fb14282334a561186eabc53e30db68d26c2c5cd41bd67cce1c218558fc64977
|
|
BLAKE2b-256 checksum How to use checksums |
33894d1fe03277ff5794d55423d28b11887f581ed4948f69b31aa69a60540817
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for git-chronos 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.