Turn your Git history into billable hours — and invoices.
A local-first CLI for freelancers and contract developers. No timers to forget,
no cloud, no AI services — your .git folder already knows when you worked.
You write code first, commit second — Git-Chronos reads your commit history and reconstructs billable sessions automatically:
- Zero manual tracking — hours are derived from real commits, not timers.
- Session-aware — gaps longer than a threshold count as unpaid breaks; a warm-up buffer is added before each session's first commit.
- Task attribution —
TASK-123:orfeature:prefixes map sessions to tasks. - Two report styles — a Rich terminal dashboard and a corporate Excel invoice with real
=SUM()formulas. - Private by design — 100% offline; nothing leaves your machine.
Python 3.10+ is required.
pip install git-chronosOr straight from GitHub:
pip install git+https://github.com/KokosP/git-chronosOr from source:
git clone https://github.com/KokosP/git-chronos
cd git-chronos
pip install .git-chronos init # creates ~/.git-chronos.toml
git-chronos status # validates config, shows your rate
git-chronos analyze . # analyzes the repo in the current directorySet developer.email in the config to your git config user.email — only your
commits are counted.
| Command | Description |
|---|---|
git-chronos init |
Creates the default ~/.git-chronos.toml config file (--force to overwrite) |
git-chronos status |
Validates the config and prints current settings |
git-chronos analyze [PATH] |
Analyzes the repository at PATH (default: .) |
| Flag | Description |
|---|---|
--period, -p |
week, month (default), or custom |
--export, -e |
terminal (default), excel, or both |
--since / --until |
Date bounds YYYY-MM-DD (required for --period custom) |
--currency, -c |
Override currency for this run (USD, EUR, GBP, …) |
--rate, -r |
Override the hourly rate for this run |
--all |
Count commits across all branches and tags, not only HEAD |
git-chronos analyze ~/work/client-app --period month --export both
git-chronos analyze . --period custom --since 2026-10-01 --until 2026-10-15
git-chronos analyze . --all --currency EUR --rate 40The Rich panel shows:
- Header — developer, client, company, repository, period, rate.
- Daily breakdown — sessions, hours, an activity bar, amount, and tasks per day.
- Per-task breakdown — hours and money per detected task.
- Finance line —
Total due: 8.2 h × $25.00 = $206.25.
On terminals with a limited legacy encoding the glyphs fall back to ASCII
(#, -, currency codes) — the numbers stay the same.
--export excel writes a styled .xlsx next to your working directory:
- Slate Gray (
#34495E) header with white text, alternating row shading. - Formats: dates
YYYY-MM-DD, hours0.0, money"$"#,##0.00. - Real formulas: per-day
=Hours*Rateand=SUM(...)totals — the invoice recalculates if you edit it.
git-chronos init writes ~/.git-chronos.toml:
[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 a session
[reporting]
company_name = "Freelance Inc."
client_name = "Best Customer LLC"Known symbols: $, €, £, ¥, ₹, ₽, ₴, ₸ and more — any other ISO
code is used as-is (SEK25.00).
flowchart LR
A[commits<br/>by your email] --> B[grouped<br/>by day]
B --> C{gap between<br/>commits}
C -->|≤ session_gap_hours| D[same session<br/>billable]
C -->|> session_gap_hours| E[break<br/>unpaid]
D --> F[+ first_commit_buffer_mins<br/>per session]
E --> F
F --> G[task prefix?<br/>TASK-123: / feature:]
G --> H[report:<br/>hours × rate = amount]
- Commits are read via GitPython (HEAD, or every ref with
--all) and filtered bydeveloper.email. - Sorted chronologically, grouped by calendar day.
- Consecutive commits within
session_gap_hoursform one session; the gap between sessions is rest and is not billed. first_commit_buffer_minsis added before each session's first commit — code exists before it is committed.- A session inherits the task from the first commit message matching
PREFIX-123:orword:; otherwise it isGeneral.
git-chronos/
├── git_chronos/
│ ├── __init__.py
│ ├── cli.py # Typer commands: init / status / analyze
│ ├── config.py # ~/.git-chronos.toml loading & validation
│ ├── git_parser.py # Commit extraction via GitPython
│ ├── analyzer.py # Sessions, buffers, task detection
│ └── exporters/
│ ├── __init__.py
│ ├── excel.py # Styled .xlsx invoice (openpyxl)
│ └── terminal.py # Rich dashboard
├── docs/ # Demo assets for this README
├── pyproject.toml
├── README.md
└── LICENSE
| Library | Purpose |
|---|---|
typer |
Command-line interface |
gitpython |
Reading local Git history |
toml |
Config parsing |
rich |
Terminal dashboard |
openpyxl |
Excel invoice generation |
No external APIs. No AI services. Python 3.10+.
This project is licensed under the MIT License.
Copyright (c) sbgid.com
