Greengrid

A terminal dashboard for your GitHub contributions and any local git repo — contribution heatmap, weekday×hour punchcard, commit log, code hotspots, conventional-commit stats, contributor bus factor, language mix, per-repo/author breakdown, streaks, lines changed, and an embeddable SVG export. Built with Ink (the React-for-terminals renderer).

Install

npm install -g greengrid
# or run once without installing:
npx greengrid

The installed binary is greengrid. local mode requires Node.js ≥ 20; github mode additionally needs Node ≥ 22.13 (for the built-in node:sqlite) and fails with a clear upgrade message on older Node.

Usage

greengrid                    # interactive TUI for the git repo you're in
greengrid local ~/code/app   # analyze another local repo (offline, no token)
greengrid github --sync      # pull your GitHub data (all repos incl. private) and explore
greengrid local --report     # non-interactive text summary (pipes/CI friendly)
greengrid local --svg out.svg # export the heatmap as an embeddable SVG

Commands

| command | what it does | |---|---| | local [path] | Analyze a local repo via git log (no network). Default: current dir. | | github | Your GitHub account — every repo incl. private. Needs a token. | | info | Show version, cache location, and auth status. | | update | Update greengrid to the latest version from npm. | | help | List all commands and options. | | version | Print the version. |

If no command is given, greengrid behaves like local .. A bare path (greengrid ~/code/app) is shorthand for local. Unknown commands print a friendly error with a suggestion.

Options

| flag | applies to | meaning | |---|---|---| | --sync | github | crawl fresh data before showing (first run auto-syncs) | | --full | github | re-crawl every repo, not just changed ones | | --db <path> | github | cache location (default ~/.greengrid/greengrid.db) | | --author <a> | local | only commits by an author (name/email substring) | | --since <when> | local | only commits after a date (2024-01-01, "3 weeks ago") | | --until <when> | local | only commits before a date | | --all | local | include all branches, not just the current one | | --tab <name> | both | open the TUI on a tab: overview/calendar/punchcard/code/log/repos | | --svg <file> | both | write the heatmap to an SVG file and exit | | --report | both | print a static text summary instead of the TUI | | --json | both | print the raw activity data as JSON | | --no-color | both | disable color (also respects NO_COLOR) | | -v, --version | | print version | | -h, --help | | show help |

The report/JSON output is also emitted automatically when stdout isn't a TTY, so greengrid local | cat and CI pipelines just work.

GitHub auth

github mode reads your data through GitHub's official GraphQL API. Provide a token via GITHUB_TOKEN, or just be logged in with the gh CLI (gh auth login). For private repositories the token needs repo scope. Only 1 API point is spent per query — nowhere near the 5,000/hour limit.

Keys (TUI)

| key | action | |---|---| | ← / →, [ / ], Tab | switch tabs | | 1–6 | jump to a tab | | ↑ / ↓, PgUp / PgDn | scroll | | r | refresh (github mode) | | q | quit |

Tabs

Overview (stats + mini heatmap + top repos/authors) · Calendar (full heatmap) · Punchcard (weekday×hour) · Code (hotspots, conventional-commit breakdown, language mix) · Log (scrollable commit list) · Repositories/Authors.

License

MIT © Niravcanvas