Commit Clock

A web app to track your GitHub commits against a daily target and see how far ahead or behind you are — live on your iPhone home screen.

Users sign in with GitHub, install a lightweight GitHub App, set a daily target, and get a personal URL for a Scriptable widget. A push to any of their repos updates their stats in real time.

Browser ─ Sign in with GitHub (OAuth) ─▶ Next.js (Vercel) ─▶ Postgres
        ─ Install GitHub App (per user) ─┘        ▲
push to a user's repo ─ GitHub App webhook ───────┘  recompute that user's stats
iOS widget ─ GET /api/stats?key=<widget key> ─▶ Next.js ─▶ JSON (display only)

Everything server-side runs on Vercel (the website, GitHub auth, the webhook receiver, and the per-user stats API) backed by Postgres. The iOS widget is the only piece on your phone — it just reads your personal stats URL.

• Today — commits made today vs. your daily target, with a progress bar.
• Bank — your running surplus/deficit. Target 5/day, did 8 today → +3, carried forward. Green when ahead, red when behind.

Commit counts are recomputed from GitHub on every push; the time-based math (days elapsed, today's reset at midnight) is computed on every read, so the numbers stay correct even on days you don't push.

web/                  the Next.js app (the whole backend + website)
  prisma/schema.prisma data model (users, targets, cached counts, auth tables)
  src/lib/            db, github commit logic, auth, per-user stats
  src/app/            pages + API routes (auth, webhook, setup, stats, settings)
widget/
  commit-clock.js     the Scriptable iOS widget (display only)
docs/
  website-setup.md    full step-by-step setup (START HERE)
  cron-vs-webhook.md  why real-time webhooks beat a polling cron

Full instructions: docs/website-setup.md. In short:

1. Database — provision Postgres, set DATABASE_URL.
2. GitHub OAuth App — for "Sign in with GitHub".
3. GitHub App — webhook → /api/github/webhook, subscribe to Push, installable by any account.
4. Env + schema — fill web/.env, run npx prisma db push.
5. Deploy to Vercel — set Root Directory to web/, add env vars, deploy.

1. Sign in to the deployed site, install the GitHub App, and copy your personal stats URL from the dashboard.
2. Install Scriptable (free), tap +, paste in widget/commit-clock.js, and set STATS_URL to your personal URL.
3. Home screen → long-press → + → Scriptable → add a Small or Medium widget → Edit Widget → Script: Commit Clock.

Tapping the widget opens your dashboard, where the target and start date live.

• What counts as a commit: GitHub's totalCommitContributions — the green contribution-graph rule. Not issues, PRs, or reviews.
• Freshness: data updates within seconds of a push; the widget face refreshes on iOS's schedule (or instantly when you tap it).
• Cost: free for a personal/small deployment (Vercel hobby + free Postgres tier + GitHub Apps).
• Local dev: cd web && npm install && npm run dev. See the setup guide for testing webhooks locally via a tunnel.