A beautiful GitHub contribution visualizer for the terminal.

ghgarden fetches your GitHub contribution data and renders it as a rich, interactive terminal dashboard — contribution heatmap, streak stats, language breakdown, and recent repo activity. Instant startup, smooth navigation, beautiful color output.

---

---

Quick Start

# Clone & build
git clone https://github.com/8tp/ghgarden.git
cd ghgarden
cargo build --release

# Run it
./target/release/ghgarden <username>

# Or with cargo
cargo run -- <username>

Authentication

A GitHub personal access token is required (the public API rate-limits unauthenticated requests aggressively).

Create a token: github.com/settings/tokens → Generate new token (classic) → select read:user scope.

# Option 1: Environment variable (recommended)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Option 2: Pass directly
ghgarden 8tp --token ghp_xxxxxxxxxxxx

# With the token set, you can omit the username
ghgarden    # auto-detects from token

Add export GITHUB_TOKEN=ghp_xxx to your ~/.zshrc or ~/.bashrc to make it persistent.

Usage

ghgarden [OPTIONS] [USERNAME]

Arguments:
  [USERNAME]    GitHub username to view

Options:
  -y, --year <YEAR>      Year to display (default: current)
  -t, --theme <THEME>    Color theme [default: garden]
      --token <TOKEN>    GitHub personal access token
  -h, --help             Print help

ghgarden 8tp                      # View a profile
ghgarden 8tp --year 2024          # Specific year
ghgarden 8tp --theme synthwave    # With a theme
ghgarden                          # Your own profile (needs token)

Themes

Six built-in themes. Press t to cycle through them live, or set one on launch:

Theme	Palette	Flag
garden	Classic GitHub greens	--theme garden
forest	Deep greens & teals	--theme forest
ocean	Cool blues	--theme ocean
sunset	Warm oranges & reds	--theme sunset
synthwave	Neon purples & pinks	--theme synthwave
monochrome	Clean white & grays	--theme monochrome

Keybindings

Key	Action
← → / h l	Switch year
↑ ↓ / j k	Navigate panels
t	Cycle color theme
?	Toggle help overlay
q / Esc	Quit

Dashboard Panels

Contribution Garden — Full-year heatmap grid. Each cell represents a day, colored by contribution intensity. Month labels aligned above, legend below.

Stats — Total contributions, current streak, best streak, average per day, best single day, plus breakdowns for commits, PRs, issues, and reviews.

Top Languages — Horizontal bar chart of your most-used languages across repos, rendered with each language's actual GitHub color.

Recent Repos — Your 8 most recently updated public repos with language indicator, star/fork counts, and relative timestamps.

Architecture

src/
  main.rs          CLI parsing, terminal setup, async event loop
  app.rs           App state, panel navigation, year switching
  github.rs        GitHub GraphQL client, response types, file caching
  theme.rs         6 color themes with 5-level intensity scales
  utils.rs         Streak calculations, relative time, number formatting
  ui/
    mod.rs         Layout engine, responsive breakpoints, loading/error states
    heatmap.rs     Contribution grid with Unicode block characters
    stats.rs       Stat card with streak and contribution breakdowns
    languages.rs   Bar chart with GitHub language colors
    repos.rs       Repo list with language dots, stars, forks, timestamps
    header.rs      Top bar with username, display name, year selector
    help.rs        Centered overlay with keybinding reference

Tech Stack

Crate	Purpose
ratatui	Terminal UI framework
crossterm	Cross-platform terminal backend
reqwest	HTTP client (rustls, no OpenSSL)
tokio	Async runtime
clap	CLI argument parsing
chrono	Date handling
serde	JSON serialization

Performance

• Non-blocking fetch — The UI renders immediately with a loading spinner while data loads in the background via tokio::spawn.
• Response caching — API responses are cached to /tmp/ghgarden_<user>_<year>.json for 15 minutes. Repeated runs are instant.
• No OpenSSL — Uses rustls for TLS, so there's no system OpenSSL dependency. Builds cleanly on macOS, Linux, and Windows.
• Tiny binary — Release builds are fast and small.

Building from Source

Prerequisites: Rust toolchain (1.70+)

git clone https://github.com/8tp/ghgarden.git
cd ghgarden
cargo build --release

The binary will be at ./target/release/ghgarden. Copy it to your PATH:

cp target/release/ghgarden /usr/local/bin/

License

MIT

---

_{Built with Rust, Ratatui, and the GitHub GraphQL API.}