⚡ GitLegend

Turn your Git history into a legend.

A premium, single-screen dashboard that celebrates your impact on any Git repo — GitHub Wrapped × Spotify Wrapped × an engineering performance report.

npm install -g gitlegend
cd any-git-repo
git legend

Zero dependencies · any stack · Windows / macOS / Linux · any repo size · runs 100% locally.

---

What it does

git legend detects your repo and local Git identity, streams the full commit history (memory-bounded, so huge repos are fine), detects 60+ languages & frameworks, then opens an interactive dashboard in your browser. Your code never leaves your machine.

The dashboard

• KPIs — commits, lines +/−, files changed
• Impact Score — weighted 0–100 with explainable sub-scores
• Coverage & rhythm — coverage + consistency/active-days rings
• Heatmap — GitHub-style 12-month calendar
• Activity over time — area chart (commits / lines / productivity)
• Tech distribution & module ownership
• Legend Moments — standout features, refactors, fixes & releases inferred from history
• AI Insights — offline pattern insights + optional Ask AI mode
• Contributors leaderboard, Timeline, and a shareable Wrapped recap card

Filter by contributor · date range · branch · directory · tech · file type — everything recomputes instantly. Light theme by default; toggle dark mode from the header.

Ask AI

Open the AI Insights tab, hit the ⚙️ gear, pick Claude, ChatGPT, or Gemini, and paste your own API key. Then tap a suggestion, hit Auto insights, or ask your own question.

GitLegend sends a small digest of the current view + your prompt to the provider you chose (proxied through the local server to avoid CORS). Your key stays in your browser, is never logged, and nothing is sent until you ask — leave AI mode off and GitLegend is fully offline.

Install & run

npm install -g gitlegend     # global install
git legend                   # run inside any repo
git legend ~/code/my-repo    # …or point at one by path

npx gitlegend                # one-off, no install

The binary is named git-legend, so Git exposes it as the subcommand git legend (gitlegend works too).

CLI options

git legend [path] [options]

-b, --branch <ref>       scope to one branch/ref         (default: all branches)
    --since <date>       only commits since e.g. "1 year ago"
    --max-commits <n>    cap parsed commits (huge repos)
    --no-merges          exclude merge commits           (merges included by default)
-p, --port <n>           preferred port                  (default: 7474)
    --host <addr>        bind address                    (default: 127.0.0.1)
    --no-open            do not auto-open the browser
    --user <name|email>  override the focus contributor
    --plugin <path>      load a plugin module (repeatable)
    --json               print the analyzed dataset as JSON and exit
-v, --version            print version
-h, --help               show help

By default GitLegend analyzes all branches including merges, so totals match GitHub/GitLab.

git legend --branch main --since "1 year ago" --port 8080
git legend --json > legend.json     # export analytics for CI / sharing

Extend it

Plugins — an ES module that extends the dataset and/or adds panels:

export default {
  name: 'my-plugin',
  analyze(dataset, ctx) { dataset.custom = { hello: 'world' }; },
  panels() { return [{ name: 'My panel', html: '<p>…</p>' }]; },
};

Load with --plugin ./my-plugin.js or a gitlegend.config.js at your repo root. See examples/example-plugin.js.

Programmatic API:

import { analyzeRepo, compute } from 'gitlegend';
const dataset = await analyzeRepo({ cwd: '/path/to/repo' });
const mine = compute.filterCommits(dataset.commits, { contributors: new Set([dataset.meta.focusIndex]) });
console.log(compute.aggregate(mine).totals);

How it works

git log --numstat → streaming parser → dataset → /api/data. The same compute.js (aggregation, impact score, Legend Moments, insights) runs unchanged in the CLI and the browser. No runtime dependencies — server, charts, and arg parsing are all hand-rolled.

Privacy

Runs entirely on 127.0.0.1 with no telemetry. The only time data leaves your machine is the optional Ask AI mode — and only for the provider you pick, only when you send a prompt.

Development

git clone https://github.com/faresk93/git-legend
cd git-legend
npm test                  # unit tests for the analytics engine
node bin/git-legend.js    # run against this repo

License

MIT — build legends, freely.

---

_{vibe-coded by Fares KHIARY}