| name | dev-wrapped |
| description | Turn any git repo (or a GitHub account) into a gorgeous, self-contained, Spotify-Wrapped-style year-in-review of someone's coding — a single animated HTML file plus shareable PNG cards. Use when the user asks for a "dev wrapped", "coding wrapped", "year in code", "git wrapped", "GitHub wrapped", a developer-stats recap, or a shareable summary of their commit history. |
Dev Wrapped
Generate a beautiful, shareable "Wrapped" for a developer's year in code. The
output is a single self-contained HTML file (no dependencies, works offline)
that plays like Instagram/Spotify stories, plus optional PNG share cards.
The magic isn't the stats — it's the persona reveal ("You're a Night Owl 🦉")
and the curated visual themes. Lead with those.
Workflow
1. Pick the data source
- Local (default, zero-auth, private): the git repo in the current directory.
Nothing leaves the machine. Use this unless the user asks otherwise.
- GitHub account-wide (optional): all of a user's repos via
gh. Requires
gh auth status to pass. Use when the user wants their whole year, not one repo.
2. Extract stats → stats.json
- Local:
node scripts/extract-git-stats.mjs --out stats.json
- Defaults to the last 365 days and your commits (
git config user.email).
- Useful flags:
--year 2026, --since 2026-01-01, --all-authors,
--author <name|email substr>, --repo <path>.
- GitHub:
node scripts/extract-github-stats.mjs --user <login> --out stats.json
(per-hour data isn't available from GitHub; the hour scene auto-hides.)
- Full metric list + exact commands: reference/metrics.md.
3. Compute the persona → enriches stats.json
node scripts/compute-persona.mjs stats.json
Adds derived (headline numbers) and persona (archetype + evidence). Tell the
user their persona out loud — it's the hook. Archetype rules: reference/personas.md.
4. Show, don't tell — let the user pick a theme
Don't ask the user to describe taste in words. Render 3–4 theme preview cards
and let them pick. The six themes and how to preview them: themes/THEMES.md.
Themes: midnight (default), synthwave, terminal, editorial, bubblegum, sunset.
5. Build the wrapped HTML
node scripts/build-wrapped.mjs --stats stats.json --theme <name> --out wrapped.html
Splices the data + chosen theme into templates/base.html. Open wrapped.html in
any browser — arrow keys / tap / scroll to advance. Scene catalog: templates/scenes.md.
Optional: --credit "github.com/<user>/<repo>" sets the share-card credit link,
and --label "Last 12 months" overrides the date label (otherwise the year).
6. (Optional) Export share cards
node scripts/export-png.mjs --html wrapped.html --formats story,og
Produces dev-wrapped-story.png (1080×1920) and dev-wrapped-og.png (1200×630).
This step — and only this step — needs Playwright:
npm i playwright && npx playwright install chromium. The HTML itself is zero-dep.
Customizing
- New persona → add to the
PERSONAS array in scripts/compute-persona.mjs and
document it in reference/personas.md.
- New theme → add
themes/<name>.css (just CSS custom properties) and list it in
themes/THEMES.md. No code change needed.
- New scene → add an
add(() => {...}) block in templates/base.html.
Notes
- The HTML is intentionally dependency-free: no CDNs, no web fonts, hand-rolled
SVG/CSS charts. Keep it that way — it's the trust + shareability moat.
- Scenes for empty data (no languages, no per-hour data) auto-hide.
