towow-progress
Turn your git history into a beautiful, artistic progress page. Not a boring dashboard — a narrative that tells your project's story.
Quick Start
pip install towow-progress
cd your-repo
towow-progress init # auto-detect modules, create config
towow-progress generate # build docs/progress.html
open docs/progress.html # done!
Let Your AI Set It Up
Paste this to Claude, ChatGPT, or any coding AI:
Install
towow-progress, runtowow-progress initon this repo, then customize.towow-progress.json— set a good title, subtitle, and adjust module names to be human-readable. Then runtowow-progress generateand open the result.
Your AI will analyze your repo structure and configure everything.
What You Get
- Hero section — total commits, lines changed, active days, longest streak
- Live indicator — latest commit with relative time ("3m ago")
- Scrollable timeline — daily commit activity with peak highlights
- Module trends — stacked area chart showing strategic focus shifts
- Distribution — horizontal bar chart of code by module
- Weekly velocity — line chart with acceleration/deceleration analysis
- Changelog — expandable recent commits with type badges, file counts, diffs
Single self-contained HTML file. Works offline. Deploy anywhere.
Configuration
towow-progress init creates .towow-progress.json:
{
"title": "My Project Progress",
"subtitle": "Built by a team of 3 over 120 days",
"lang": "en",
"modules": {
"src": "Core Engine",
"api": "API Layer",
"web": "Frontend",
"tests": "Test Suite",
"docs": "Documentation"
},
"colors": {
"src": "#1D4ED8",
"api": "#059669",
"web": "#EA580C",
"tests": "#7C3AED",
"docs": "#0891B2"
},
"output": "docs/progress.html",
"accent_color": "#1D4ED8",
"accent_secondary": "#EA580C",
"background": "#F7F4F0",
"font_family": "",
"branding": true
}
What you can customize
| Field | What it does | Example |
|---|---|---|
title |
Big hero title | "Acme Engine" |
subtitle |
Line under the title | "3 engineers · 200 days" |
modules |
Map directory prefixes to display names | {"src": "Core"} |
colors |
Hex color per module | {"src": "#1D4ED8"} |
accent_color |
Primary brand color (borders, links, charts) | "#8B5CF6" (purple) |
accent_secondary |
Highlight color (peaks, badges) | "#F59E0B" (amber) |
background |
Page background | "#FAFAF9" (stone) |
font_family |
Custom font stack | "'JetBrains Mono', monospace" |
output |
Where to write the HTML | "public/progress.html" |
branding |
Show "Powered by Towow" footer | true / false |
Color presets
Default (warm ivory + blue)
{ "accent_color": "#1D4ED8", "accent_secondary": "#EA580C", "background": "#F7F4F0" }
Dark academia
{ "accent_color": "#78350F", "accent_secondary": "#B45309", "background": "#FEFCE8" }
Cyberpunk
{ "accent_color": "#7C3AED", "accent_secondary": "#EC4899", "background": "#FAF5FF" }
Forest
{ "accent_color": "#065F46", "accent_secondary": "#D97706", "background": "#F0FDF4" }
Auto-Update with GitHub Actions
towow-progress setup-ci
This creates .github/workflows/towow-progress.yml. On every push to main, it regenerates and commits the HTML.
Deploy to GitHub Pages:
- Run
towow-progress setup-ci - Go to repo Settings → Pages → Source:
Deploy from a branch→ Branch:main, folder:/docs - Push. Your progress page is live at
https://username.github.io/repo/progress.html
How It Works
- Scans git history —
git log --numstatto get per-file additions/deletions - Classifies files — maps file paths to modules using your config
- Computes analytics — daily/weekly/monthly aggregations, velocity, streaks
- Renders HTML — single file with inline CSS + Chart.js from CDN
No database. No server. No API keys. Just git + Python.
Powered by Towow — AI-native collaboration protocol
Metadata
Release files for towow-progress 0.1.1
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 |
|---|---|---|---|---|
| towow_progress-0.1.1.tar.gz | 15.8 kB | Without provenance | Details for towow_progress-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| towow_progress-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for towow_progress-0.1.1-py3-none-any.whl |
Total release size: 32.8 kB
Release files / towow_progress-0.1.1.tar.gz
| Download URL | towow_progress-0.1.1.tar.gz |
|---|---|
| Size | 15.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d28cdfe975984763806bf9581bbde14f6452923566e2c049c8a9b3cceea6291e
|
|
BLAKE2b-256 checksum How to use checksums |
67cba36ac3f0b3ba33d5f2398cd2552a826b88a40c535f6274ffcd3a9661c4e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / towow_progress-0.1.1-py3-none-any.whl
| Download URL | towow_progress-0.1.1-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95f799de2a45f75e1d6e7cdf827d12fcf644d24b7497f181aa0fc9acea1b1e46
|
|
BLAKE2b-256 checksum How to use checksums |
df70ab4d30091d5afb9428f47ce69862b3044e36760b99c5601390093333f09d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for towow-progress 0.1.1
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.