❯ shellrecap

Spotify Wrapped for your terminal — what does your shell history say about you?

npx shellrecap        # reads your shell history — and never uploads a byte of it

You typed git status one thousand times this year. You retyped the same 27-character kubectl incantation two hundred times instead of making an alias. You committed gti status to history 31 times. And somewhere in that file there may be a token you once pasted into a command line, sitting in plaintext.

shellrecap reads your zsh/bash/fish history and turns it into a recap — your top commands, the hour you actually work, your typo hall of shame, the aliases you're owed (with exact keystrokes saved), and any secrets you've left in the file (always masked). A persona card sums you up, exportable as an SVG made for posting.

Your shell history is full of paths, hostnames, and credentials — the one file you should never paste into a website or a chatbot. So shellrecap runs entirely on your machine: no hooks to install, no account, no network. It just reads the file your shell already writes.

  🦉  The Night Owl
     Your terminal sees more moonlight than sunlight.

  7,140 commands   ·   56 unique   ·   41 different programs

  Top commands
  git     ██████████████████████ 2,178
  cd      ████████               761
  ls      ███████                729

  When you type  (peak 2 AM · Monday)
  ▇██▆▁▁▁▁▁▂▃▃▃▃▃▃▃▃▃▆▆███

  Typos  sl→ls ×86 · gti→git ×69 · cd..→cd .. ×48 · claer→clear ×39
  316 mistyped commands · 1,145 wasted keystrokes

  Aliases you're owed  (could have saved 48,031 keystrokes)
  alias kgpp='kubectl get pods -n production'
    typed 197× — saves 5,122 keystrokes

  ⚠ 3 possible secrets in your history
    ghp_FA… GitHub token — entry #546

Why shellrecap?

• 🎤 The roast you can't get elsewhere. GitHub has a wrapped. Spotify has a wrapped. Your terminal — where you actually live — has nothing. Until now.
• 🔒 Built for the one file you must not upload. No hooks, no daemon, no account, no network calls. It reads ~/.zsh_history (or bash/fish) locally and computes everything in-process. The shareable card shows only command names and counts — never full command lines, which can contain hostnames and paths.
• 🎁 It pays you back. Alias suggestions are computed from what you actually retype, ranked by exact keystrokes saved — copy-paste one line into your rc file.
• 🧹 It might save you an incident. Tokens, AWS keys, -p passwords, and inline SECRET= vars left in history are detected and reported masked, with the entry number so you can delete the line.
• 🧠 Deterministic, zero-dependency core. Same history → same recap. The pure engine is browser-safe (a paste-and-see playground is on the roadmap).

Install

# run it now, no install
npx shellrecap

# or keep it around
npm install -g shellrecap

Node ≥ 18. Works with zsh (plain & EXTENDED_HISTORY), bash (plain & HISTTIMEFORMAT), and fish. Time-of-day stats appear when your history has timestamps; everything else works regardless.

Quick start

shellrecap                          # auto-finds your history (most recent shell wins)
shellrecap ~/.bash_history          # point at a specific file
shellrecap --shell fish             # force a format
shellrecap doctor                   # list the history files it can see (paths only)
shellrecap report                   # write shellrecap.svg + .md + .json to share
shellrecap report --theme candy     # tokyonight | dark | light | candy
history | shellrecap --stdin        # pipe anything

What it figures out

| Group | What you get | | ----- | ------------ | | Persona | One of ten (🦉 Night Owl, 🧙 Pipe Wizard, 🔱 Sudo Summoner, 🐙 Git Gremlin, 🐳 Container Captain, 🧘 Vim Monk, 🎨 Typo Artist, 🧭 Navigator, 🌐 Polyglot, 🎛️ Steady Operator) — picked by deterministic rules | | Top commands | Programs and "favorite moves" (git status, docker compose…), pipe & sudo rates | | Rhythm | Commands by hour/weekday, peak hour, night-owl & weekend share, busiest day (needs timestamps) | | Typos | Curated classics (gti, sl, claer…) plus edit-distance detection against your own top commands — with wasted-keystroke totals | | Aliases you're owed | Exact long commands you retype, suggested alias names, keystrokes each would save | | Secrets | GitHub/AWS/Slack/Stripe/npm tokens, JWTs, -p passwords, inline SECRET= vars — always masked, with the entry number to delete |

Real scenarios

1. Post your card. Run shellrecap report, open the SVG, screenshot, post. The card carries only command names and counts — safe by construction.

2. Actually fix your workflow. Paste the top alias suggestion into your .zshrc and stop retyping that 30-character kubectl line 200 times a year:

shellrecap | grep "alias "   # → alias kgpp='kubectl get pods -n production'

3. Audit your history for leaked credentials. CI keys get pasted into terminals more often than anyone admits:

shellrecap --quiet --json recap.json   # secrets[] lists kind + entry number, masked

Configuration

shellrecap init writes shellrecap.config.json:

{
  "theme": "tokyonight",     // card theme
  "top": 8,                   // how many top commands / suggestions
  "aliasMinCount": 10,        // suggest an alias after this many repeats
  "aliasMinLength": 12,       // …for commands at least this long
  "ignoreCommands": [],       // base commands to exclude entirely
  "secretScan": true          // set false to skip the secret check
}

Flags override config. --tz <minutes> pins the timezone for reproducible time stats (defaults to this machine's offset).

Library API

The core is pure and browser-safe — feed it history text from anywhere:

import { parseHistory, analyze, renderCard, DEFAULT_CONFIG } from "shellrecap";

const { entries, format } = parseHistory(rawHistoryText);
const report = analyze(entries, DEFAULT_CONFIG, {
  sourceLabel: "~/.zsh_history",
  format,
  tzOffsetMin: 540,
});

console.log(report.persona.title, report.aliases.totalSavable);
const svg = renderCard(report, "tokyonight");

Privacy, precisely

• Reads your history file(s) read-only, locally. No network code exists in this package — grep dist/ if you like.
• The terminal output may show full command lines (it stays in your terminal).
• The SVG card and Markdown/JSON exports never include full command lines or secret values — commands appear as names + counts, secrets only as masked previews (ghp_FA…).

Roadmap

• 🌐 Browser playground — paste history, see your card, 100% client-side (the engine already runs in a browser).
• 🐚 Atuin (SQLite) and PowerShell (ConsoleHost_history.txt) support.
• 📊 Multi-file merge (zsh + bash on the same machine).
• 🤖 Optional --ai layer (bring-your-own key) for a written "year in your terminal" paragraph. The core stays 100% offline and deterministic.

💖 Sponsor

shellrecap is free and MIT-licensed, built in spare time. If it made you laugh, saved you keystrokes, or caught a leaked token:

• ⭐ Star this repo — the simplest free way to help others find it.
• 🍋 Sponsor via Lemon Squeezy — one-time or recurring.

License

MIT © shellrecap contributors