towow-progress 0.1.1

AI-native development progress dashboard — turn your git history into a beautiful narrative page.

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, 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