hackfetch

A Hack Club themed system fetch with live Hackatime stats. Shows your system info next to a customizable Hack Club logo, plus your today/weekly hours, top project, top language, streak, and more. All from your terminal, in one keystroke.

hackfetch was built for Stardance, Hack Club's worldwide hackathon. It runs as a single Go binary with zero runtime dependencies, reads your existing ~/.wakatime.cfg, and pulls live stats from Hackatime every time you run it.

Why hackfetch
What it does
Gallery
Architecture
Getting started
- 1. Install
- 2. Connect to Hackatime
Usage
Logos and color schemes
Custom themes
Live mode and card export
Status bar integration (tmux + nvim)
Doctor
Caching
True-color gradients
7-day sparkline
Configuration
What you get from Hackatime
Repository layout
Status
License

Why hackfetch

Most "fetch" tools (neofetch, fastfetch, and the rest) show the same things: OS, kernel, CPU, memory, uptime. They are great, and also they do not know anything about what you are actually building.

Hack Club runs its own coding-time tracker, Hackatime, a WakaTime-compatible backend that aggregates your real coding stats: today's hours, weekly total, top project, current streak. Those are the numbers worth caring about when you open a terminal.

hackfetch is what happens when you cross a fetch tool with that data and then style the whole thing in Hack Club colors and ASCII art.

Built for the Hack Club crowd. Six built-in Hack Club logos, themed gradients, Pride flag palettes, and the Stardance countdown baked in.
Zero runtime dependencies. Pure Go, single binary. Works on minimal Linux containers, fresh macOS installs, and stock Windows alike.
Live updating. Open it with -watch and your stats refresh in place while you code.

What it does

hackfetch runs as one Go binary that pulls four things together at once:

System fetch. OS, hostname, user, shell, terminal, editor. The classic neofetch-style snapshot of the machine you are on, rendered next to a Hack Club logo.
Hackatime stats. Today's coding time, 7-day total, current streak, top project, most-used language, top editor, top category. Pulled live from your Hackatime account every time you run the command.
Live mode. hackfetch -watch keeps the fetch on screen and redraws every 30 seconds. Your hours tick up as you code, in the corner of your terminal.
Card export. hackfetch -export card.png (or .jpg, or .svg) saves the current fetch as a shareable image with all colors preserved. Drop it into a devlog, a Slack channel, or a tweet.
Status bar mode. hackfetch -status prints a compact one-line summary for tmux status-right, lualine, or any other status bar that shells out to a command.
Self-diagnosis. hackfetch -doctor walks a colored checklist of your setup (config, api key, network, terminal, browser) and tells you exactly what to fix if anything is red.
Leaderboard. hackfetch -leaderboard daily (or weekly) shows the top 10 Hack Club hackers with clickable links to their Hackatime profiles.
JSON output. hackfetch -json dumps the fetched data as machine-readable JSON, ready to pipe into your own scripts or status bars.
On-disk cache. Repeat runs read from ~/.cache/hackfetch/last.json and return in ~20ms instead of ~700ms, so a tmux status bar polling every minute is effectively free.
24-bit color. Auto-detects COLORTERM=truecolor and emits smooth interpolated gradients on modern terminals. Falls back to 256-color on everything else.

All rendering happens locally in your terminal. No browser, no dashboard, no extra processes.

Gallery

Default Hack Club logo, forest gradient.

Trans flag colors on the default Hack Club logo.

The rocket logo in default colors.

The flag logo in sunset gradient.

The bot logo on a matrix-green scheme.

The Stardance logo in ocean gradient.

Architecture

   terminal ──► hackfetch (single Go binary)
                    │
                    ├──► local system info  (os, host, user, shell, terminal, editor)
                    │
                    ├──► Hackatime API      (today, weekly, streak, top project, top lang)
                    │        │
                    │        └──► smart fallbacks: when Hackatime says "unknown" for
                    │                              language, infer from heartbeat file
                    │                              extensions and label as (inferred)
                    │
                    ├──► layout engine      (pads each logo row, aligns info column)
                    │
                    └──► render targets     (ANSI 256-color terminal, or PNG/JPG/SVG card)

A single binary, one network round-trip per refresh, no daemon. The same render pipeline drives both the one-shot fetch and the -watch live mode. The card exporter shares the layout engine and can emit PNG, JPEG, or SVG depending on the output file extension; PNG/JPG are rasterized in-process using an embedded copy of DejaVu Sans Mono so no system fonts or external converters are needed.

Getting started

1. Install

The fastest way on any Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/xerneas3318/hackfetch/main/install.sh | sh

The installer auto-detects your OS, CPU architecture, and package manager (apt, dnf, yum, pacman, zypper, apk, or brew), installs any missing prereqs (curl, tar, xdg-utils), then drops the right binary into /usr/local/bin (or ~/.local/bin if it can't sudo). POSIX sh compatible, so it also works on Alpine and minimal containers.

On Windows (PowerShell):

irm https://raw.githubusercontent.com/xerneas3318/hackfetch/main/install.ps1 | iex

Installs hackfetch.exe to %LOCALAPPDATA%\Programs\hackfetch and adds that folder to your user PATH.

Alternative install paths:

# Homebrew (macOS, Linuxbrew)
brew tap xerneas3318/tap
brew install hackfetch

# AUR (Arch, CachyOS, Manjaro, EndeavourOS, etc.)
yay -S hackfetch-bin      # or: paru -S hackfetch-bin

# From source with Go
go install github.com/xerneas3318/hackfetch@latest

The AUR package lives at aur.archlinux.org/packages/hackfetch-bin and pulls the pre-built release binary, so there's no Go build step on the user's machine. Works on x86_64 and aarch64.

2. Connect to Hackatime

hackfetch reads your API key from ~/.wakatime.cfg. If you already use Hackatime or WakaTime, you're done.

If not, the easiest path is Hack Club's official setup:

curl -fsSL https://raw.githubusercontent.com/hackclub/hackatime-setup/main/install.sh | bash

Or run hackfetch -setup and it will walk you through the auth page at hackatime.hackclub.com/my/wakatime_setup and wait for the config file to land.

Usage

hackfetch                              # defaults
hackfetch stardance rainbow            # positional shorthand: <logo> <color>
hackfetch logo flag color pride        # keyword form
hackfetch -logo orpheus -color ocean   # flag form
hackfetch -v                           # verbose: + slack, 7-day chart, machines, top editor, top category
hackfetch -watch                       # live mode, refreshes every 30s
hackfetch -export card.png             # save the fetch as a shareable image (.png/.jpg/.svg)
hackfetch -status                      # one-line summary for tmux/lualine status bars
hackfetch -status -sparkline           # same, with 7-day bar chart appended
hackfetch -doctor                      # diagnose setup, api, network, terminal
hackfetch -leaderboard daily           # top 10 hackers today (weekly too)
hackfetch -json                        # dump all fetched data as JSON
hackfetch -list                        # show all logos and colors
hackfetch -h                           # help
hackfetch -setup                       # (re-)configure Hackatime
hackfetch -no-cache                    # skip the on-disk cache and force a fresh fetch
hackfetch -no-net                      # offline mode (skip API calls)

Flags go before positional args. hackfetch -export card.png stardance pride works; hackfetch stardance pride -export card.png does not.

Logos and color schemes

	Available
Logos	`hackclub`, `stardance`, `flag`, `orpheus`, `bot`, `rocket`, `pizza`
Solid colors	`hackclub`, `orange`, `mono`, `mute`, `matrix`
Gradients	`rainbow`, `sunset`, `ocean`, `forest`, `stardance`
Pride flags	`pride`, `trans`, `bi`, `pan`
Special	`auto` (defaults to `pride` in June, `hackclub` otherwise)

Run hackfetch -list for the same table, printed live from the binary:

$ hackfetch -list
logos:
  bot
  flag
  hackclub
  orpheus
  pizza
  rocket
  stardance

colors:
  bi
  bisexual
  forest
  hackclub
  matrix
  mono
  mute
  ocean
  orange
  pan
  pansexual
  pride
  rainbow
  stardance
  sunset
  trans

And hackfetch -h for the full flag reference:

$ hackfetch -h
hackfetch: hack club system fetch

usage:
  hackfetch [logo] [color] [flags]
  hackfetch logo <name> color <name> [flags]

examples:
  hackfetch                              # defaults
  hackfetch stardance rainbow            # shorthand
  hackfetch logo flag color pride        # keyword form
  hackfetch -logo orpheus -color ocean   # flag form

flags:
  -color string    color scheme (see -list) (default "hackclub")
  -export string   export the fetch as an image (e.g. card.png, card.jpg, card.svg)
  -list            list available logos and color schemes
  -logo string     logo name (see -list) (default "hackclub")
  -no-net          skip api calls (offline mode)
  -setup           re-run the api key setup flow
  -v               verbose: also show slack, 7-day chart, machines, editor, category
  -watch           live mode: refresh every 30s until ctrl+c

Custom themes

Drop your own color schemes in ~/.config/hackfetch/colors.json:

{
  "schemes": {
    "vaporwave": {
      "colors": [199, 165, 99, 51],
      "mode": "per-line"
    },
    "fire": {
      "colors": [196, 202, 208, 214, 220, 226],
      "mode": "per-char"
    }
  }
}

mode is one of single, per-line, or per-char. colors are ANSI 256 color codes. Your themes override built-ins of the same name. Then run:

hackfetch -color vaporwave

Live mode and card export

Live mode (-watch). Re-fetches your Hackatime stats every 30 seconds and redraws in place. Today's hours tick up as you code. Ctrl+C to quit.

hackfetch -watch
hackfetch rocket -watch -color sunset

Card export (-export). Saves the current fetch as a shareable image with rounded corners, dark background, and every color preserved. The output format is picked from the file extension:

.png: full-color raster, rendered in-process with an embedded monospace font. Best for uploading to Slack, Discord, Stardance devlogs, or anywhere else that won't accept SVG.
.jpg / .jpeg: same rendering, JPEG-encoded at quality 92. Smaller file, no transparency.
.svg: original vector output. Open it in any browser; scales cleanly to any size.

hackfetch -export card.png
hackfetch -export card.jpg stardance pride
hackfetch -export card.svg -logo orpheus -color rainbow

Status bar integration (tmux + nvim)

hackfetch -status prints a compact one-liner meant for status bars. It's non-interactive (never launches setup, exits silently if hackatime isn't configured, silent on API errors) so it's safe for anything that polls a command every few seconds.

$ hackfetch -status
2h 11m today · hackfetch (45m) · streak 12

tmux. Add to ~/.tmux.conf:

set -g status-right "#(hackfetch -status)"
set -g status-interval 60

Every session, every window, refreshing once a minute.

Neovim (lualine). Add a lualine section that shells out:

require('lualine').setup {
  sections = {
    lualine_z = {
      function()
        return vim.fn.system("hackfetch -status"):gsub("\n", "")
      end
    }
  }
}

Combined with the on-disk cache below, both are basically free after the first fetch of the minute.

Doctor

hackfetch -doctor walks a colored checklist of your setup and tells you what's broken.

$ hackfetch -doctor

  ✦ hackfetch doctor

  ✓ wakatime config exists       /Users/xerneas/.wakatime.cfg
  ✓ api_key present              loaded from hackatime.hackclub.com
  ✓ wakatime-cli found           /Users/xerneas/.wakatime/wakatime-cli
  ✓ hackatime api reachable      today: 28m (327ms)
  ✓ terminal supports truecolor  $COLORTERM=truecolor
  ✓ browser opener available     /usr/bin/open

  ✓ everything looks good

Green if it works, orange if it doesn't, short hint on any failing line. Exits non-zero on failure so you can script it in CI or install checks.

Caching

Every fetch checks ~/.cache/hackfetch/last.json first. If the snapshot is younger than the per-mode TTL, hackfetch skips the network entirely and renders from disk.

mode	TTL	typical cost
`hackfetch`	30s	~23ms on hit vs ~700ms cold
`hackfetch -status`	60s	~6ms on hit vs ~700ms cold
`hackfetch -watch`	(ignored)	always fresh

Reasons this exists: fewer TLS handshakes = less battery drain, offline resilience (tmux bar keeps working when wifi drops), and being nice to the free Hackatime API.

Opt out with -no-cache or HACKFETCH_CACHE_TTL=0. Override the TTL with HACKFETCH_CACHE_TTL=300 (seconds). Point the cache elsewhere with HACKFETCH_CACHE=/path/to/file.json.

Writes are atomic (.tmp + rename), so nothing ever reads a torn file. The cache is mode 0600 because it contains your top project name.

True-color gradients

Gradient schemes (rainbow, sunset, ocean, forest, stardance) auto-detect 24-bit color support via $COLORTERM and emit smooth interpolated colors instead of stepping through the 256-color palette. Terminals without truecolor support fall back to the classic quantized cycle automatically.

Force it either way:

HACKFETCH_TRUECOLOR=1 hackfetch stardance rainbow   # force smooth
HACKFETCH_TRUECOLOR=0 hackfetch stardance rainbow   # force fallback

The card exporters (SVG/PNG/JPG) always use smooth interpolation since they aren't constrained by terminal color depth.

7-day sparkline

A little unicode bar chart of your last seven days of coding time shows up as 7-day chart in the normal fetch, and can be tacked onto -status with --sparkline:

$ hackfetch -status --sparkline
2h 20m today · streak 9 · ▄▄▇▅▄▅▃ 65h 39m

Oldest day on the left, newest on the right. Days with no activity render as a space so light weeks don't get confused with active ones. The tallest bar always hits ▇/█ so the chart scales to whatever your peak day was.

Same data source as the streak (/heartbeats/spans on the native Hackatime API), so no extra round-trip cost.

Configuration

hackfetch reads these environment variables. Add them to your ~/.zshrc or ~/.bashrc to set defaults:

Variable	Default	Purpose
`HACKFETCH_LOGO`	`hackclub`	Default logo (see `-list`).
`HACKFETCH_COLOR`	`hackclub`	Default color scheme.
`HACKFETCH_VERBOSE`	unset	Set to `1` to enable `-v` output by default.
`HACKFETCH_STARDUST`	unset	Your stardust count. Shown next to the ✦ field.
`HACKFETCH_TRUECOLOR`	(auto)	Force 24-bit color on (`1`) or off (`0`). Auto-detects from `$COLORTERM` by default.
`HACKFETCH_CACHE`	`~/.cache/hackfetch/last.json`	Path to the on-disk response cache.
`HACKFETCH_CACHE_TTL`	(per-mode)	Cache TTL in seconds. `0` disables. Overrides the built-in per-mode defaults.
`HACKFETCH_DEBUG`	unset	Set to `1` to log API calls and cache decisions to stderr.
`HACKFETCH_INSTALL_DIR`	(auto)	Override the install directory used by `install.sh`.
`WAKATIME_HOME`	`$HOME`	Where to look for `.wakatime.cfg`.

What you get from Hackatime

When your ~/.wakatime.cfg points at a working Hackatime account, hackfetch fetches and shows:

Field	Meaning
today	Hours coded today.
7-day total	Hours coded over the past week.
streak	Consecutive days with activity.
stardust ✦	Your stardust count (set via `HACKFETCH_STARDUST=N`).
stardance	Days left until Stardance ends (auto-hides after Sep 30, 2026).
top project	Most-worked project (today and weekly).
top language	Most-used language. When Hackatime reports `unknown`, hackfetch infers from heartbeat file extensions and labels it `(inferred)`.
slack	(verbose) Your Hack Club / Hackatime handle. Enable with `-v`.
7-day chart	(verbose) 7-day sparkline of coding time. Enable with `-v`.
machines	(verbose) When you've coded on more than one machine in the past 7 days. Enable with `-v`.
top editor	(verbose) Most-used editor. Enable with `-v`.
top category	(verbose) coding / debugging / building / etc. Enable with `-v`.

Repository layout

Path	Contents
`main.go`	Flag parsing and entry point.
`logos.go`	Every built-in ASCII logo.
`colors.go`	Color schemes, ANSI codes, and the ANSI-to-hex table.
`config.go`	Reads `~/.wakatime.cfg`.
`hackatime.go`	HTTP client, response caches, parallel prefetch, language inference.
`sysinfo.go`	OS, shell, editor, terminal, hostname.
`setup.go`	Interactive `-setup` flow.
`render.go`	Terminal render, `-status` one-liner, watch loop, loading spinner.
`export.go`	SVG / PNG / JPG card exporters.
`cache.go`	On-disk response cache (`~/.cache/hackfetch/last.json`) with per-mode TTL and atomic writes.
`doctor.go`	`-doctor` diagnostic checklist.
`assets/`	Embedded resources: DejaVu Sans Mono (Bitstream Vera License) used for raster export.
`install.sh`	POSIX shell installer for Linux and macOS. Auto-installs prereqs via the system package manager.
`install.ps1`	PowerShell installer for Windows (10/11, amd64 and arm64).
`Formula/hackfetch.rb`	Homebrew formula (used by the `xerneas3318/tap` tap).
`packaging/aur/`	Source of truth for the AUR packages (see the README in that folder for publish steps).
`.github/workflows/release.yml`	CI: builds 6 cross-platform binaries on every tag and publishes the GitHub release.
`Images/`	Gallery screenshots used in this README.

Status

v2.1.0 is the current release. What ships in the box today:

Cross-platform binaries built on every tag for Linux, macOS, and Windows (x86_64 and arm64).
Install anywhere in one line: the POSIX curl installer auto-installs missing prereqs across seven package managers, plus a PowerShell installer for Windows.
Homebrew tap for macOS and Linuxbrew: brew tap xerneas3318/tap && brew install hackfetch.
AUR package for the Arch family: yay -S hackfetch-bin on Arch, CachyOS, Manjaro, EndeavourOS, Garuda, etc.
Seven built-in Hack Club logos (hackclub, stardance, flag, orpheus, bot, rocket, pizza) and fifteen color schemes including a full Pride flag pack.
Real streak computed from /heartbeats/spans (/summaries was silently dropped from the Hackatime API; hackfetch now reconstructs streak from raw span data instead).
7-day sparkline (▄▄▇▅▄▅▃) in the fetch and optionally in -status --sparkline.
Live -watch mode that redraws in place every 30 seconds.
Status bar mode (-status) for tmux and lualine integration.
Self-diagnosis (-doctor) that walks a colored checklist and tells you exactly what's broken.
Public leaderboard (-leaderboard daily or weekly) shows the top 10 Hack Club hackers with OSC 8 clickable links to each user's Hackatime profile.
JSON output (-json) dumps every fetched field for scripting: today, week, streak, top project, per-day chart, and system info.
On-disk response cache so repeat runs return in ~20ms instead of ~700ms and tmux polling is basically free.
24-bit color auto-detection with smooth interpolated gradients on modern terminals (fallback to 256-color on older ones).
Card export in SVG, PNG, and JPG (raster path uses an embedded copy of DejaVu Sans Mono so box drawing, block shading, and Unicode symbols all render correctly).
Loading spinner on stderr while the Hackatime fetch runs.
Parallel Hackatime fetch with a shared HTTP client and connection pool: a full cold fetch that used to take ~1.7 seconds now takes ~0.7 seconds (and ~20ms warm).
Custom color themes via ~/.config/hackfetch/colors.json.
Smart language inference when Hackatime reports unknown: falls back to file extensions from the raw heartbeat log.

Related Hack Club tooling and inspirations:

Stardance, the Hack Club hackathon hackfetch was built for.
Hackatime, Hack Club's WakaTime-compatible coding-time backend.
Hack Club, the worldwide community of teen hackers.
nFetch, the dependency-free Go system-fetch that inspired the architecture here.
neofetch, the original genre-defining fetch.

License

PolyForm Noncommercial 1.0.0. Fork it and tinker for fun, just don't sell it.

Maintained by @xerneas3318.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

hackfetch

Contents

Why hackfetch

What it does

Gallery

Architecture

Getting started

1. Install

2. Connect to Hackatime

Usage

Logos and color schemes

Custom themes

Live mode and card export

Status bar integration (tmux + nvim)

Doctor

Caching

True-color gradients

7-day sparkline

Configuration

What you get from Hackatime

Repository layout

Status

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github/workflows		.github/workflows
Formula		Formula
Images		Images
assets		assets
packaging/aur/hackfetch-bin		packaging/aur/hackfetch-bin
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
cache.go		cache.go
colors.go		colors.go
config.go		config.go
doctor.go		doctor.go
export.go		export.go
go.mod		go.mod
go.sum		go.sum
hackatime.go		hackatime.go
install.ps1		install.ps1
install.sh		install.sh
instructions.md		instructions.md
json_out.go		json_out.go
leaderboard.go		leaderboard.go
logos.go		logos.go
main.go		main.go
render.go		render.go
setup.go		setup.go
sparkline.go		sparkline.go
sysinfo.go		sysinfo.go

Folders and files

Latest commit

History

Repository files navigation

hackfetch

Contents

Why hackfetch

What it does

Gallery

Architecture

Getting started

1. Install

2. Connect to Hackatime

Usage

Logos and color schemes

Custom themes

Live mode and card export

Status bar integration (tmux + nvim)

Doctor

Caching

True-color gradients

7-day sparkline

Configuration

What you get from Hackatime

Repository layout

Status

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages