ghpulse

Every GitHub stats tool generates the same boring stat cards. Rectangles with numbers. Progress bars. Language percentages. It's been done a thousand times.

ghpulse turns your GitHub activity into generative visual art — unique to you, based on your actual data. Your repos, languages, contribution patterns, and activity shape the output.

Every theme ships in dark and light variants — pass <theme> for the dark version, <theme>-light for the light. Pair them with GitHub's #gh-dark-mode-only / #gh-light-mode-only URL fragments to auto-switch in your README.

Your code universe as a cosmic map. Each repo is a star sized by contribution intensity, colored by primary language, connected by constellation lines when repos share languages. Stars pulse with a subtle twinkle animation.

Cyberpunk retro-terminal aesthetic. Green-on-black monospace text. Stats typed out like you're hacking into mainframes in 1987. Blinking cursor included.

Spider/radar chart mapping your language dimensions. Axes generated from your actual language distribution. The shape of the radar is unique to your skill mix.

Enhanced contribution heatmap. Like GitHub's contribution graph but denser, with month labels, a legend, and your stats summary.

A unique visual hash of your developer identity. Horizontal bars arranged like an audio waveform. The pattern is deterministic — same data always produces the same image.

Retrowave sunset: striped neon sun, magenta perspective grid receding to the vanishing point, and language pillars rising from the horizon like an EQ display.

White light enters a glass prism on the left and refracts into a fan of language-colored beams on the right. Each beam's thickness is proportional to that language's share.

# Generate with default theme (nebula)
ghpulse --token "$ACCESS_TOKEN"

# Pick a theme
ghpulse --token "$ACCESS_TOKEN" --theme terminal

# Exclude repos and languages
ghpulse --token "$ACCESS_TOKEN" --exclude-repos "test-*,forks/*" --exclude-langs "HTML,CSS"

# Save raw data, then re-render offline
ghpulse --token "$ACCESS_TOKEN" --dump-json stats.json
ghpulse --from-json stats.json --theme radar --output ./out

# PNG export (requires --features png)
ghpulse --token "$ACCESS_TOKEN" --format both

ghpulse [OPTIONS]

  -t, --token <TOKEN>              GitHub personal access token [env: ACCESS_TOKEN]
      --theme <THEME>              Visualization theme [default: nebula]
      --format <FORMAT>            Output format: svg, png, both [default: svg]
  -o, --output <DIR>               Output directory [default: .]
      --exclude-repos <PATTERNS>   Comma-separated glob patterns
      --exclude-langs <LANGS>      Comma-separated language names
      --exclude-private            Skip private repos
      --exclude-archived           Skip archived repos
      --min-stars <N>              Minimum stars to include a repo
      --min-commits <N>            Minimum commits to include a repo
      --dump-json <FILE>           Save raw stats to JSON
      --from-json <FILE>           Render from cached JSON (no API calls)
      --list-themes                List available themes
      --list-langs                 List detected languages
      --theme-dir <DIR>            Load custom themes from directory
      --max-retries <N>            Max retries for flaky API endpoints [default: 10]
      --verbose                    Verbose output
      --debug                      Debug output
  -V, --version                    Print version

Add this to your profile README repo:

# .github/workflows/ghpulse.yml
name: Generate Stats

on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: QaidVoid/ghpulse@v1
        with:
          token: ${{ secrets.ACCESS_TOKEN }}
          theme: nebula
          exclude-repos: "test-*"

      - name: Commit
        run: |
          git config user.name "ghpulse[bot]"
          git config user.email "ghpulse[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update ghpulse stats" || true
          git push

Then in your README:

![My GitHub Universe](./nebula.svg#gh-dark-mode-only)
![My GitHub Universe](./nebula-light.svg#gh-light-mode-only)

Themes are TOML files. Drop them in a directory and point --theme-dir at it:

name = "My Theme"
background = "#0d1117"
foreground = "#c9d1d9"
accent = "#58a6ff"
font = "JetBrains Mono, monospace"
width = 800
height = 400

[star]
min_radius = 2
max_radius = 12
glow = true

[connection]
opacity = 0.15
width = 0.5

[animation]
twinkle = true
duration = "4s"

ghpulse --token "$TOKEN" --theme my-theme --theme-dir ~/.config/ghpulse/themes

Repos are discovered through your commit contributions, so anything you've actually committed to (org repos, forks, OSS projects) surfaces regardless of token type. Repos you own but never committed to won't appear.

Minimum for public data: read:user. Add read:org for org-admin attribution and repo for private repos and traffic.

Repository permissions

• Metadata — Read (required)
• Contents — Read
• Administration — Read (only for traffic/view counts)

For org repos, the org owner must:

1. Enable fine-grained tokens in Org Settings → Personal access tokens → Allow access via fine-grained personal access tokens.
2. Approve your token if approval is required.

When creating the token, set Resource owner to each org you want included (one token per resource owner). If your org doesn't allow fine-grained tokens, use a classic PAT instead.

git clone https://github.com/QaidVoid/ghpulse.git
cd ghpulse
cargo build --release

# with PNG support
cargo build --release --features png

MIT OR Apache-2.0