gitpulse

A live terminal dashboard for any git repository. Point it at a repo and get a year of contribution heat, a commit sparkline, an author leaderboard, the files your team keeps touching, and working-tree status — all in one frame that refreshes while you work.

Zero runtime dependencies. It shells out to git and draws with escape codes.

Install

git clone https://github.com/dustfillerr-code/gitpulse.git

cd gitpulse && npm install && npm run build

Then run it anywhere:

node /path/to/gitpulse/dist/index.js ~/code/my-project

Or link it onto your PATH as gitpulse:

npm link

Requires Node 18+ and git on your PATH.

Usage

gitpulse                    # dashboard for the current repo
gitpulse ~/code/linux       # ...or any other one
gitpulse --interval 3       # refresh every 3 seconds
gitpulse --once             # print one frame and exit

Options

Flag	Default	What it does
-i, --interval <seconds>	10	Auto-refresh interval
-w, --weeks <n>	52	Heatmap window
-d, --days <n>	30	Sparkline window
--hot-days <n>	90	Hot-files window
-1, --once	—	Render one frame and exit
--color / --no-color	auto	Force colour on or off
-h, --help	—	Show help

Keys

Key	Action
q, Esc, Ctrl-C	Quit
r	Refresh now
Space	Pause / resume auto-refresh

What each panel tells you

• Activity — a commit-per-day heatmap over the last year. Colour is scaled against the single busiest day, so a quiet repo still shows contrast rather than a wall of the same shade.
• Commits per day — the last 30 days as a sparkline, with peak and daily average. This is the panel that shows whether a push actually landed.
• Authors — who has been committing inside the heatmap window, ranked, with a stable colour per rank that the commit log reuses.
• Hot files — the paths changed most often in the last 90 days. Merge commits are excluded so the counts reflect real edits.
• Recent — the last commits, with relative timestamps.

The header carries branch, short HEAD, ahead/behind against the upstream, and a working-tree summary (staged / modified / untracked / conflicted).

Notes on the implementation

A few things that were more interesting than expected:

• Strings stop being their own width once they carry ANSI codes, so everything in src/ansi.ts is width-aware — truncate walks escape sequences so a cut never lands inside one and never leaks colour.
• Layout degrades top-down. render adds panels while vertical budget remains, so a 24-row terminal drops the commit log instead of scrolling the frame. Below 88 columns the two-up row collapses to one.
• Dates are bucketed in the viewer's timezone via --date=format-local:%Y-%m-%d, so "today" is genuinely the rightmost column of the heatmap rather than whatever timezone the committer was in.
• --no-color moves the ramp into the glyph ( ░▒▓█) instead of the foreground, so piped output stays readable.
• The README screenshot is generated, not pasted. scripts/screenshot.mjs runs a real frame and converts the ANSI output to SVG, pinning each run with textLength so the grid holds together in whatever monospace font your browser picks.

Development

npm run typecheck && npm run build

Regenerate the README image against any repo:

node scripts/screenshot.mjs ../some-repo docs/screenshot.svg 104 38

License

MIT