WaifuFetch

System info fetcher with a waifu logo from a persistent playlist, powered by waifu.im (default) with nekos.best and ComfyUI as alternatives (mixable via weighted source config).

Displays system information alongside a background-removed anime image rendered natively in the terminal via the kitty graphics protocol. Images are played in sequence from a persistent playlist that never deletes — it grows toward a configurable cap (default 50), keeping API usage bounded. Images are pre-fetched and processed in the background so execution is instant.

System info is gathered by a built-in display.py (no fastfetch dependency).

Features

• Instant display — uses cached images, no waiting on startup
• Persistent playlist — images are never deleted; played in sequence, auto-grows toward the cap
• Background queue — fetches in a detached worker when fewer than 5 images remain
• Multi-source — waifu.im (default) / nekos.best / ComfyUI (image generation), mixable by weight (source = { waifuim = 3, comfyui = 1 }), configurable per-source options (orientation, NSFW rating, tags, ordering, API key)
• Background removal — AI-powered segmentation via rembg/isnet-anime
• Fallback — empty cache falls back to a bundled default image
• In-terminal images — renders actual PNGs via the kitty graphics protocol's Unicode-placeholder method (flow-based, works with any font/settings)
• No fastfetch — system info gathered natively by display.py

Dependencies

Package	Purpose
ImageMagick	Image trimming and resizing
Python 3.10+	display.py / worker / sources runtime
curl	Image downloads
Any terminal with kitty-graphics Unicode-placeholder support	Image rendering (kitty confirmed; Ghostty reports support)

Terminal compatibility: waifufetch renders images with the Unicode-placeholder method of the kitty graphics protocol (U=1 virtual placements + U+10EEEE placeholder cells) so the image participates in normal text flow. This is a distinct subset of the protocol — kitty is the reference implementation (tested), and Ghostty reports support. Terminals that implement only basic kitty-graphics image placement (WezTerm, Konsole, foot, iTerm2) do not implement Unicode placeholders, so the image will not render there (the system info text still displays).

The install script creates a self-contained Python venv with:

• rembg[cpu] — background removal (isnet-anime model, ~176MB downloaded once)
• Pillow — image handling
• requests — HTTP client

Install via paru

Install — one command:

curl -fsSL https://5d.fyi/waifufetch | bash

Adds my package repo to paru, syncs it, and installs. Prefer not to run a script? Add the repo by hand, then sync and install:

mkdir -p ~/.config/paru && printf '[fifthdread]\nUrl = https://forgejo.fifthdread.com/Fifthdread/pkgbuilds.git\nSkipReview\n' >> ~/.config/paru/paru.conf
paru -Sy --pkgbuilds
paru -S waifufetch-git

Updates come with paru -Su.

The first waifufetch run creates the Python venv (rembg, a minute or two) and pre-fetches a few images; playback is instant after that.

Manual install

# Clone or download the repo anywhere, then run install from within it
git clone ssh://git@forgejo.fifthdread.com:223/Fifthdread/waifu_fetch.git /tmp/waifu_fetch
cd /tmp/waifu_fetch
./install.sh

The install script:

1. Checks all system dependencies (exits with instructions if missing)
2. Copies project files to ~/.local/share/waifufetch/ (you can delete the clone after)
3. Creates a Python venv with rembg[cpu]
4. Writes a default config to ~/.config/waifufetch/config.toml
5. Symlinks waifufetch → ~/.local/bin/waifufetch
6. Pre-fetches 5 images to ~/.config/waifufetch/images/

Ensure ~/.local/bin is in your $PATH. After install, just type waifufetch in any compatible terminal.

Note

: If you run waifufetch from .zshrc, disable p10k's instant prompt — it intercepts stdout and corrupts the kitty graphics escape sequences.

Config

Edit ~/.config/waifufetch/config.toml. The file generated on first run (or by waifufetch --migrate-config) is fully commented — every option is explained. Re-run waifufetch --migrate-config after an upgrade to get any new options added with comments while keeping your settings (the previous file is backed up to config.toml.bak.<timestamp>):

cap = 50
source = "waifuim"

[colors]
mode = "auto"
header = "keys"
kitty_theme = true
ansi_theme = false
style = "bold"

[sources.waifuim]
orientation = "PORTRAIT"
is_nsfw = false
gif = false
included_tags = []
excluded_tags = []
order_by = "RANDOM"
api_key = ""

[sources.nekos]
category = "waifu"

[sources.comfyui]
base_url = ""
api_key = ""
workflow_dir = ""
workflows = []
collection = ""
random_seed = true
match_orientation = true
gen_timeout = 600

• cap — playlist size cap. Once reached, fetching stops (delete images to resume).
• source — active provider(s): waifuim (default), nekos, comfyui, or a weighted table like source = { waifuim = 3, comfyui = 1 } to pull from several at once. Search and NSFW runs only use sources that support them.
• waifuim.* — orientation (always PORTRAIT), SFW/NSFW rating, animated GIFs, tag filters, ordering, optional API key (higher rate limits).
• nekos.category — nekos.best category (default waifu).
• comfyui.* — generate images via a ComfyUI server. Workflows are API-format JSON exports ("Save (API Format)") in workflow_dir (default ~/.config/waifufetch/workflows/), selected by workflows (empty = all). collection (empty = top level) names a subfolder used as an opt-in collection pool — e.g. collection = "succubus" uses workflow_dir/succubus/*.json; waifufetch --collection succubus --raw forces it for one run and --list-collections lists the subfolders. random_seed (default on) randomizes seeds so each generation is fresh; match_orientation (default on) swaps the latent to portrait; gen_timeout caps one generation (seconds). base_url is the ComfyUI endpoint, api_key optional.
• colors.* — display theming. mode "auto" detects the top-4 dominant colors from each image; "custom" uses only the hex values below (no detection). style picks the color mood: "bold" (default) merges the dominant colors with the most vivid image accents (fetch role #1 = the terminal foreground, so the text always carries the waifu's punchiest hue); "subtle" uses the soft k4-dominant colors only. Both styles are pre-computed together at fetch time, so switching is free. Roles keys (labels), output (values), title, separator accept "#rrggbb" (omitted = auto/terminal default). header colors the user@host title line — a role reference (default "keys") or a literal hex. kitty_theme (default true) restyles the terminal to match each waifu — bg/fg/cursor always; a full 16-color ANSI slot restyle too when ansi_theme (default false) is enabled — applied via OSC escape codes (no kitty config needed; current window only, no-op on unsupported terminals). Slots stay off by default because prompts that draw from the ANSI palette (p10k chips etc.) stay readable on any system that way. Image-derived colors are lifted in OKLab (perceptual lightness raised while chroma is held), so they stay vivid and readable on the dark background.

Usage

Command	What it does
waifufetch	Show the next cached image (instant)
waifufetch -d	Delete the last-displayed image (file, playlist entry + color caches) and show the next. Bare -d is smart — it deletes whatever's on screen wherever it lives (a namespace, nsfw, hentai); -p/--nsfw/--hentai pin the target playlist explicitly
waifufetch -r / --raw	Fetch a fresh random image now (blocks), adds it to the playlist
waifufetch -s "maid" / --search "maid"	Search the source by tag/term, adds it to the playlist
waifufetch --add N [SOURCE] / -n / --new	Fetch N new images in the background into the playlist (no N = 5; trailing SOURCE pins the provider, e.g. --add 20 comfyui)
waifufetch --source NAME	Pin the source for this run (waifuim/nekos/comfyui); works with --raw/--search/--add, overrides config
waifufetch -p NAME / --playlist NAME	Use a named playlist namespace (images/ns_<NAME>): its own cache + sequence, independent of the SFW playlist (works with --raw/--add/-d/-S/-c). A pinned --source/--collection also applies to the namespace's background seed/refill — waifufetch -p succubus --collection succubus keeps that playlist fed only from succubus workflows
waifufetch --list-collections	List the comfyui workflow collection subfolders
waifufetch --no-bg	Skip background removal
waifufetch --category waifu	Source-specific category (nekos.best)
waifufetch --nsfw	Play the next cached NSFW image (separate opt-in playlist; seeds 5 in the background on first use)
waifufetch --nsfw --raw	Fetch a fresh random NSFW image (blocks), adds it to the NSFW playlist
waifufetch --nsfw --search "tag"	Search the source for NSFW matches by tag/term
waifufetch --hentai	Play the next cached hentai-tagged image (separate opt-in playlist; seeds 5 in the background on first use)
waifufetch --hentai --raw	Fetch a fresh random hentai-tagged image (blocks), adds it to the hentai playlist
waifufetch --clear-cache	Wipe all cached images (SFW + NSFW + hentai + namespaces) and start fresh; with -p wipes only that playlist
waifufetch --shuffle	Shuffle the playlist (SFW by default) and display the next image
waifufetch --version	Show version and exit
waifufetch --help	Show usage
waifufetch --color	Force the waifu-matched terminal theme (overrides colors.kitty_theme: false)
waifufetch --no-color	No image-derived colors — plain text, no terminal restyle (use your own theme)
waifufetch --no-fetch-color	Plain fetch text; keep the terminal theme
waifufetch --no-bg-color	Keep fetch text colors; no terminal background/theme restyle
waifufetch --bold / --subtle	Force the bold (merged) or subtle (k4) color style for this run
waifufetch --migrate-config	Regenerate the config with comments, preserving your settings (backs up the old one)
waifufetch --precache-colors	Backfill color caches for all cached images (one-time speedup after upgrades)

Uninstall

If installed via paru, first remove the package (pacman -R waifufetch-git), then clean up the user-space files:

rm ~/.local/bin/waifufetch
rm -rf ~/.local/share/waifufetch
rm -rf ~/.config/waifufetch

Files

File	Description
waifufetch.sh	Entry point — playlist playback + kitty-graphics image rendering
sources.py	Image source providers (waifuim, nekos) + config loader
waifu_fetch_url.py	CLI helper that prints a direct image URL from the configured source
waifu_worker.py	Background worker — fetches, processes, appends to the playlist
display.py	System info display + kitty placeholder-grid rendering
palette.py	Extracts dominant colors from the image for theming
waifu_fetch.json	Module config for display.py
bootstrap.sh	Shared venv + config init (install.sh / packaged first-run)
~/.config/waifufetch/	Runtime state (config.toml)
~/.config/waifufetch/images/	Images, per-cache playlists, temp files + TOML caches (palettes/themes/sysinfo)
~/.local/share/waifufetch/.venv/	Python venv (created on install or first run, gitignored)

--nsfw routes to a separate opt-in cache at ~/.config/waifufetch/images/nsfw/ (own .playlist/.pos), so NSFW never mixes into the SFW rotation and is never pre-fetched except during an explicit --nsfw invocation. waifu.im is the only source with NSFW support; others error cleanly.