Skip to main content

towow-progress

Turn your git history into a beautiful, artistic progress page. Not a boring dashboard — a narrative that tells your project's story.

MIT License

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, run towow-progress init on this repo, then customize .towow-progress.json — set a good title, subtitle, and adjust module names to be human-readable. Then run towow-progress generate and 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:

  1. Run towow-progress setup-ci
  2. Go to repo Settings → Pages → Source: Deploy from a branch → Branch: main, folder: /docs
  3. Push. Your progress page is live at https://username.github.io/repo/progress.html

How It Works

  1. Scans git history — git log --numstat to get per-file additions/deletions
  2. Classifies files — maps file paths to modules using your config
  3. Computes analytics — daily/weekly/monthly aggregations, velocity, streaks
  4. 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)

Source distribution for towow-progress 0.1.1
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)

Table of built distributions (wheels) for towow-progress 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page