code-wrapped

---
name: code-wrapped
description: Turn someone's git history into a "Wrapped"-style year-in-review story, a set of bold vertical cards (commits, lines written and deleted, coding hours heatmap, latest-night commit, longest streak, busiest day, top languages, most-touched file, biggest commit, commit-message habits, collaborators and a coding personality), with captions written for that person from their real commits. Produces one offline HTML story you tap through, plus 1080×1920 PNGs and an MP4 ready for Instagram, X or LinkedIn. Use when someone asks for their coding year in review, "Wrapped for my code / commits / GitHub", a recap or stats of their repos, a fun summary of a project's history for a team, or something shareable about what they built this year, even if they never say "Wrapped".
license: MIT
---

# Code Wrapped

The person gets their year in code told back to them as a story: big numbers, loud colors, one idea per card, and captions that sound like they were written by a friend who read every commit. The numbers come from a script. **The captions come from you.** That is the whole point of this being a skill rather than a script: a template says "You made 175 commits"; you say "175 commits, and 20 of them on October 17. What happened on October 17?"

`SKILL_DIR` is the folder this file is in. Everything runs on Node 18+ and git with no `npm install`. PNG export needs Chrome, Chromium, Edge or Brave. The video needs `ffmpeg`.

## Workflow

### 1. Decide the scope (don't ask unless it's unclear)

- **Which repos.** Default: the current repo. "All my projects" or a folder → pass the folder; the collector finds every repo up to 3 levels down. Several paths are fine.
- **Who.** Default: the identity in each repo's `git config user.name` / `user.email`. If they commit under other names or emails, add `--author` for each (substring match on name or email). For a team or project recap use `--everyone`.
- **When.** Default: the current calendar year. `--year 2025`, `--last 365`, or `--since 2026-03-01 --until 2026-06-30`.

### 2. Collect

```bash
node "$SKILL_DIR/scripts/collect.mjs" <repo-or-folder>... [--author "name or email"]... [--everyone] [--year YYYY | --last N] --out wrapped-out
```

It writes `wrapped-out/stats.json` and prints a one-line summary. If it exits with "No commits matched", it prints the authors it did see; pick the right `--author` (or ask, if it's genuinely ambiguous) and run again. Lockfiles, vendored and build folders, and any single-file change over 5,000 lines are left out of line counts (they're counted in `totals.skippedGeneratedLines`).

Put `wrapped-out` in the folder the person is working in, not in a temp or scratch folder: they need to find the PNGs to post them. If that folder is a git repo, tell them `wrapped-out/` is untracked and offer to add it to `.gitignore`, so their stats don't get committed by accident.

### 3. Read stats.json and find the story

Read the whole file. Before writing a word, look for the 4–6 things that are *specific to this person*: the commit at 3:52 AM and what it said, the file they touched 27 times, the month they disappeared, the word they overuse, the day with 20 commits, the language that's 83% of everything, the commit that deleted a million lines. If a detail is interesting, `git show <hash> --stat` or `git log` around a date to learn what actually happened. Specifics are what make people share it.

### 4. Write `wrapped-out/copy.json`

Every field is optional; anything you leave out falls back to a decent default. Wrap a word or two in `*asterisks*` to color it with the card's accent. Plain text only, no HTML.

```json
{
  "intro":       { "title": "Alex, 2026 was *a lot*.", "body": "3 repos. 175 commits. One very tired keyboard." },
  "commits":     { "kicker": "This year you made", "title": "commits.", "body": "88 of them landed in *October alone*." },
  "lines":       { "kicker": "Lines of code", "body": "For every 3 lines you wrote, you *deleted 2*." },
  "rhythm":      { "kicker": "Your rhythm", "title": "Your hour was *11 PM*.", "body": "..." },
  "latenight":   { "kicker": "Latest commit of the year", "body": "..." },
  "streak":      { "kicker": "Longest streak", "body": "..." },
  "busiest":     { "kicker": "Your busiest day", "title": "...", "body": "..." },
  "languages":   { "kicker": "Your top languages", "title": "...", "body": "..." },
  "topfile":     { "kicker": "Your ride-or-die file", "body": "..." },
  "biggest":     { "kicker": "Your biggest commit", "body": "..." },
  "messages":    { "kicker": "Your commit messages, decoded", "body": "..." },
  "crew":        { "kicker": "Your crew", "title": "..." },
  "personality": { "kicker": "Your coding personality is", "title": "*The 4 AM Architect*", "body": "..." },
  "summary":     { "title": "That's a wrap.", "body": "Made with code-wrapped · a Claude skill" },
  "skip": ["crew"]
}
```

Any card can also take `"theme"`: one of `ember ultra lime plum ink peach teal pink cream night`.

What each card shows on its own, so your words add to it instead of repeating it: `commits` shows the big number (your `title` is the word under it); `lines` shows +added/−deleted with bars; `rhythm` shows a 7×24 heatmap; `latenight` shows the clock time and the commit message; `streak` shows the day count and a contribution calendar; `busiest` shows the date; `languages` shows the ranked bars; `topfile` shows the path and commit count; `biggest` shows +/− and the message; `messages` shows a word cloud and one "desperate" commit; `crew` shows bars per collaborator.

**The voice.** Write like Wrapped, not like a report:

- **Short.** A title is at most ~6 words; a body is one or two sentences, at most ~25 words. The cards are phones.
- **Specific beats clever.** Name the file, quote the commit, say the date. "You and `Editor.tsx` have been through 27 commits together" beats "You had a favorite file!"
- **Affectionate roast.** Tease the habits (3 AM commits, "fix fix fix", a 90-character message), never the person's skill or worth. Celebrate the big stuff sincerely.
- **Every number is real.** Only use numbers that are in stats.json or that you computed from it. Don't invent percentiles ("top 1% of developers") or comparisons you can't back.
- **Collaborators are off-limits for jokes.** Thank the crew; never roast someone who isn't the reader.
- **Personality.** Keep the computed archetype, or give it a sharper name grounded in the data ("The 4 AM Architect", "The Refactor Monk"). The tagline is one line.
- **Team mode (`--everyone`).** Address the team or project ("Inkwell, ..."), not "you".

### 5. Privacy pass (required before any export)

The cards quote commit messages, file paths and repo names, and people will post them publicly. Before exporting, scan what will show: `latestCommit.subject`, `biggestCommit.subject`, `messages.desperateSamples`, `messages.mostRepeated`, `topFiles[0]`, `repos[].name`, `crew[].name`. If anything looks like a client name, a secret, an internal codename, a ticket with customer data, or a collaborator who might not want to be named, tell the person and either skip the card (`"skip": [...]`) or ask before going ahead. Mention which cards quote what, in one line, when you hand the result over.

### 6. Build, look, export

```bash
node "$SKILL_DIR/scripts/build.mjs" --dir wrapped-out          # → wrapped-out/wrapped.html (offline, one file)
node "$SKILL_DIR/scripts/export.mjs" --dir wrapped-out --video  # → wrapped-out/cards/*.png (1080×1920) + wrapped.mp4
```

Look at the PNGs before you hand them over (read a few, or tile them with `ffmpeg -pattern_type glob -i 'wrapped-out/cards/*.png' -vf "scale=360:640,tile=7x2" -frames:v 1 sheet.png`). Check that no caption is cut off or wraps into a mess, and that the story reads well in order. If a caption is too long, shorten it in copy.json and rebuild; never edit the template for one person's copy.

Open `wrapped.html` for them. Controls: tap or → for next, ← for back, hold or Space to pause. `#card=5` jumps to a card. `#static` turns off motion.

## Hand-off

Tell them, in a few lines: where `wrapped.html`, the PNGs and the MP4 are; the one or two best cards to post (usually `personality` and `summary`); and what got quoted (step 5).

## Files

- `scripts/collect.mjs`: reads git history and computes every stat, including the personality archetype.
- `scripts/build.mjs`: bakes `stats.json` + `copy.json` into `template/wrapped.html`.
- `scripts/export.mjs`: headless Chrome screenshots each card; ffmpeg turns them into a story video.
- `template/wrapped.html`: the story player and the card designs. Edit this to add or restyle cards for everyone.
- `references/stats-schema.md`: what every field in stats.json means.

• .gitignore 1 KB
• LICENSE 1 KB
• README.md 3 KB
• SKILL.md 9 KB