devpulse

A pulse check for any git repository, right in your terminal. devpulse reads git log and shows a GitHub-style activity heatmap, commit streaks, top contributors, the files that change most often (hotspots) and when during the week work happens.

• Zero runtime dependencies — just Node.js and git
• Scriptable — --json emits the full report for dashboards and CI
• Filterable — by date range, author, path, and file globs
• Sensible defaults — lockfiles and build output don't drown out real code churn

Quick start

git clone https://github.com/22507260/devpulse.git
cd devpulse
npm install && npm run build
node dist/cli.js -C /path/to/any/repo
# or install the command globally
npm link && devpulse --since "6 months ago"

Example

Output of npm run demo -- --weeks 20 --top 5, which builds a throwaway repository with a synthetic six-month history and runs devpulse on it (colors are shown in a real terminal):

devpulse 2026-03-28 → 2026-09-24
  284 commits · 3 contributors · 123 active days · +2988 / -0 lines
  Current streak: 12 days   Longest streak: 12 days

Activity (last 20 weeks)
     May     Jun     Jul     Aug       Sep
     · ░ · ░ ░ ░ · ░ ░ · · · · · · ░ · ░ ░ ░
Mon  ░ · █ ▓ ▒ · · ▒ █ ▓ · · ▒ · ▒ ▒ █ ▓ ▓ ░
     ░ ░ ░ · ▓ ▓ ▒ · ░ · ░ ▓ █ ▒ ▒ █ ░ ▒ █ █
Wed  ▓ ▒ █ · ▒ █ ▒ ▓ █ · ▒ · █ ▒ █ · █ ▓ ░ █
     · ▒ █ ▓ ░ · █ · · ▓ ▒ ░ ▓ █ · · ▒ · ░ ▓
Fri  █ █ █ ░ ▓ ▓ ▓ ▓ ▓ ░ ░ █ ▓ ▒ ▒ · ▓ █ ▒
     · · ░ · · · · ░ ░ ░ · ░ · ░ · · ░ · ░
     Less · ░ ▒ ▓ █ More

Top contributors
  Ada Lovelace   150    +1569 -0       ████████████████████
  Grace Hopper    78     +835 -0       ██████████
  Alan Turing     56     +584 -0       ███████

Hotspots (most frequently changed files)
   104×    1081 lines  src/engine.ts
    64×     623 lines  src/parser.ts
    48×     532 lines  src/cli.ts
    39×     398 lines  test/engine.test.ts
    29×     354 lines  README.md

When commits happen
       0  3  6  9  12 15 18 21
  Sun             .  ....•
  Mon           ●•●••.•●●●
  Tue           ••⬤••.●•••
  Wed           ⬤●••••⬤•●•
  Thu           ●••..●•.•●
  Fri           •••●●⬤⬤⬤••
  Sat           . .• •.  .

Usage

devpulse — pulse check for any git repository

Usage:
  devpulse [options] [-- <path>...]

Options:
  -C, --cwd <dir>       Repository to analyze (default: current directory)
  -s, --since <date>    Only commits after this date ("2026-01-01", "3 months ago")
  -u, --until <date>    Only commits before this date
  -a, --author <text>   Only commits whose author matches
  -w, --weeks <n>       Heatmap width in weeks (default: 26)
  -n, --top <n>         Rows in contributor and hotspot tables (default: 10)
  -x, --exclude <glob>  Ignore matching files in line counts and hotspots (repeatable)
      --all-files       Don't skip lockfiles and build output by default
      --merges          Include merge commits
      --json            Print machine-readable JSON instead of charts
      --no-color        Disable ANSI colors (also honors NO_COLOR)
  -h, --help            Show this help
  -v, --version         Show version

Examples

devpulse --since 2026-01-01 --author "Ada"     # one person's year so far
devpulse -- src/                                # only commits touching src/
devpulse -x "*.snap" -x "docs/**"               # ignore snapshots and docs in hotspots
devpulse --json | jq '.contributors[0]'         # top contributor as JSON

JSON output

--json prints a single object:

Field	Description
totals	commits, contributors, additions, deletions, active days
range	ISO timestamps of the first and last commit
streaks	current and longest run of consecutive days with commits
contributors	per-author commits, lines added/removed, first and last commit
hotspots	most frequently changed files with total line churn
perDay	{ "YYYY-MM-DD": count } in local time
punchCard	7 × 24 matrix of commits by weekday (Sunday first) and hour

How it works

git log --numstat -M --format=<record/field separators>
        │
        ▼
 parse.ts   → Commit[]  (renames normalized, binary files = 0 lines)
 filter.ts  → drop excluded files (small glob engine, .gitignore-style)
 stats.ts   → contributors · churn · punch card · per-day · streaks
 report.ts  → JSON report  ──►  render.ts → ANSI heatmap & tables

Header fields are separated with ASCII control characters (\x1e, \x1f), so commit subjects containing |, tabs or => never break parsing.

Development

npm install
npm test          # vitest: unit tests + integration tests against a temp git repo
npm run typecheck
npm run build
npm run demo      # try it on a generated sample repository

License

MIT