@sachinthapa572/gh-ascii

Turn any GitHub handle into a neofetch-style ASCII profile card in your terminal. Your avatar is converted to ASCII art and your stats (uptime, languages, repos, stars, commits, followers, contact info) are pulled live from the GitHub API — same rendering pipeline as the gh-ascii web app.

Install

# use without installing
npx @sachinthapa572/gh-ascii <handle>

# or install globally
npm install -g @sachinthapa572/gh-ascii
gh-ascii <handle>

Usage

gh-ascii torvalds

                      ─ torvalds@github ──────────────────────────
   ..::::..            . Uptime: ........................ 18 years, 3 months
 .::::::::::::.        . Location: ......................... Finland
.:::::::::::::::       . Company: .......................... Linux Foundation
.:::::::::::::::       . Languages: ........................ C, Shell, Makefile
.:::::::::::::::       . Email: ............................. [email protected]
.:::::::::::::        . Website: ........................... http://kernel.org
 '::::::::::'           . GitHub: ........................... github.com/torvalds
   '::::::'
                        ─ Contact ─────────────────────────────
                        . Repos: ............ 7 | . Stars: ...... 145230
                        . Commits: ....... 4096 | . Followers: ... 213840

Options

| Flag | Description | | ----------------------- | ------------------------------------------------------ | | <handle> | GitHub username (required) | | --theme <dark\|light> | Color theme (default: dark) | | --cols <n> | ASCII resolution, 40..160 (default: 64) | | --no-color | Disable ANSI colors | | --no-cutout | Skip ML background removal (faster, no model download) | | --side-by-side | Force portrait + stats side by side | | --stacked | Force stats below the portrait | | -h, --help | Show help | | -v, --version | Print version |

When you run gh-ascii with no handle in an interactive terminal, it prompts for one. In non-interactive contexts (piped output, CI), all decoration is skipped and only the card is printed, so gh-ascii <handle> > card.txt and gh-ascii <handle> | cat keep working cleanly.

Environment

Set GITHUB_TOKEN to raise the API rate limit (unauthenticated requests are capped at 60/hour).

How it works

The avatar → ASCII pipeline is borrowed from the best open-source converters (chafa, AAlib, Acerola's ASCII shader, jp2a):

• ML background removal (ONNX portrait matting) isolates the subject. Use --no-cutout to skip it for a fast, offline-friendly render.
• Measured glyph metrics — every printable ASCII glyph's real ink coverage per cell quadrant, baked into src/glyphs.ts.
• AAlib-style structure matching + chafa-style fill/structure split + damped Floyd–Steinberg dithering on the density residual.
• Acerola-style edge voting — Sobel directions per subcell; a / \ | - contour glyph overrides only when 3 of 4 subcells agree.

Development

vp install     # install dependencies
vp test        # run unit tests
vp check       # format, lint, type-check
vp pack        # build the CLI to dist/