README.md

crossfetch ☧

An animated Chi-Rho terminal dashboard with a liturgical-calendar heart.

The Chi-Rho (Labarum) — the Greek letters Chi (Χ) and Rho (Ρ), the monogram of Christos that Constantine adopted — detonates on your terminal in a two-colour shockwave, glows beside your system specs, and changes its colours with the seasons of the church year. Advent turns it purple, Christmastide gold, Holy Week crimson — automatically, every day, no manual steps. On major feast days a special emblem (the Star of Bethlehem, the Dove, the Crown of Thorns) plays a one-time fullscreen animation, once per feast per year.

Inspired by hyfetch — its pride-month easter egg is where the "seasonal one-shot animation" idea comes from, reimagined here around the Western liturgical calendar, and v2.1 adopts more of its feature set (palette presets, lightness adjustment, 8-bit fallback, custom ascii, backend choice, a setup wizard). Credit and thanks to the hyfetch authors. No hyfetch code is used; crossfetch is written from scratch and drives fastfetch for the system-info side.

The opening animation — silk

bin/silk is what plays when a terminal opens: a full-screen piece in the alternate buffer, faded in and out, gone on any key. Since 2026-09-07 the default is bloom — a rose, modelled in 3D from a spiral of scalloped, curling petals, that opens from a closed bud and keeps slowly turning — and its sibling cross is a Latin cross cast in gold rising out of a bank of darkness, top first, foot last, then holding to catch the light.

Both are drawn by one small software renderer: the surface is sampled by area into tens of thousands of points, lit by a warm key light, a rim light and a specular glint, painted far-to-near through a z-buffer into 2×4 sub-cells, and each terminal cell is then reduced to its two most telling colours (bright side as foreground, dark side as background) on Unicode 16 octant block glyphs — so a shaded surface actually reads as a surface. Needs numpy; a terminal that draws octants natively (kitty ≥ 0.40, foot, ghostty, WezTerm) looks best. Four flatter braille/octant pieces ship too: silk (ribbons in a flow field), marble (mathematical marbling), ridge (stacked ridgelines), loom (a precessing knot).

silk [bloom|cross|silk|marble|ridge|loom|any|cycle] [secs]
SILK_MODE=cross silk            # a different piece
silk cycle                      # rotate through them, one per launch
SILK_TIMEOUT=0 silk             # stay until a key is pressed

Variable	Meaning
SILK_MODE	which piece (default bloom); any random, cycle round-robin
SILK_TIMEOUT	seconds before auto-exit; falls back to CROSS_TIMEOUT (0 = until keypress)
SILK_FPS	frame-rate ceiling (falls back to CROSS_FPS, default 60)
SILK_TEXT	optional caption faded in at the centre
SILK_STATS	print the achieved fps to stderr on exit
NO_COLOR	do nothing at all

Screenshots

The fetch view — specs beside the glowing Chi-Rho, colors following the liturgical season:

All nine emblems — Chi-Rho, Orthodox cross, Jerusalem cross, ichthys, Star of Bethlehem, dove, crown of thorns, skull, Kali dragon (crossfetch --logo <emblem>):

Palette presets, each drawn from the church year (crossfetch --list presets):

The same logo re-skinned per preset (crossfetch --logo -p <name>):

Features

• Live animated splash in the alternate screen buffer (scrollback untouched): burst (charging symbol + banded two-colour shockwave), ring (orbiting comet), rain (falling trails), or both.
• --fetch — your specs next to the symbol, with a light-crest sweep and a lingering shimmer on the logo.
• --logo — static rainbow art on stdout, made to be embedded as a fastfetch file-raw logo.
• Liturgical engine (liturgy.py) — pure date math, no I/O: Gregorian (Meeus) Easter computus, season lookup, feast lookup.

  Season	Colours (accent roles)
  Advent	iris + subtle (purple)
  Christmastide	gold + text
  Lent	iris + muted (purple)
  Holy Week	love + muted (crimson)
  Eastertide	gold + foam
  Ordinary Time	love + gold

• Feast days — Christmas, Epiphany, Ash Wednesday, Palm Sunday, Good Friday, Easter, Ascension, Pentecost, All Saints. Each carries its own colours, a verse, and an emblem; the first interactive launch on the day plays a fullscreen burst once (recorded in ~/.local/state/crossfetch/shown.json). Replay any feast on demand: crossfetch --feast good_friday.
• Nine emblems — chi, orthodox, jerusalem, ichthys, kali, skull, star (Bethlehem), dove (Pentecost), thorns (Good Friday).
• Seven themes (ricefx.py) — rose-pine (default), rose-pine-dawn, tokyo-night, gruvbox, catppuccin-mocha, nord, dracula. Colours are role names (love gold rose pine foam iris …) resolved through the active theme, so the liturgical seasons re-skin themselves on every theme.
• fastfetch config generator — crossfetch --sync-fastfetch renders fastfetch.template.jsonc with the active theme's palette into ~/.config/fastfetch/config.jsonc, comments intact, with a contrast guard so no key colour falls below readability on the theme background.
• Daily verse — rotated from verses.txt, overridden by the feast's own verse on feast days.

New in 2.1 — the hyfetch feature set, church-year edition

• Twelve palette presets (presets.py) — named palettes drawn from Christian color symbolism instead of flags: advent (the wreath's three violet candles and the rose one), bethlehem, creation, easter, pentecost (tongues of fire), lent, holy-week, ordinary, marian, vatican, trinity, ichthys. Pick one with -p/--preset, ask for random, or pass a literal '#hex,#hex,...' list. An explicit preset outranks the liturgical season everywhere — logo, fetch glow, burst flood.
• Lightness adjustment — --c-set-l 0.65 pins the palette's HSL lightness (also accepts 65), --c-scale 1.2 multiplies it; overflow is redistributed across channels rather than clipped, so hues survive.
• Gradient direction & banding — --align diagonal|horizontal|vertical aims the gradient; --bands collapses it into discrete equal stripes, the classic banner look.
• 8-bit color fallback — --color-mode 8bit maps every escape through the xterm-256 cube, so screen sessions and the Linux console get the full show; truecolor is no longer required. The default (auto) stays conservative: it keeps truecolor unless the terminal affirmatively cannot pass RGB through (TERM=linux, screen), so existing setups render exactly as before.
• Custom ascii art — --ascii-file path.txt swaps any UTF-8 text file in for the emblem: #/space grids become square-pixel masks like the built-in symbols, anything else renders 1:1 as pre-drawn art.
• Backend choice — --backend fastfetch|neofetch picks which *fetch renders the specs block; the other is a fallback when the choice is not installed.
• Setup wizard & config file — crossfetch --setup walks color depth, theme, preset, lightness, emblem, splash mode and backend, then writes ~/.config/crossfetch/config.json. Precedence is always CLI flag > CROSS_* env > config file > auto-detection.
• Discoverability — --list presets|themes|symbols|feasts prints the valid choices (presets as color swatches), --version reports the version.

Install

git clone https://github.com/DAEMON-404/crossfetch.git ~/.config/crossfetch
install -m 755 ~/.config/crossfetch/bin/crossfetch  ~/.local/bin/crossfetch
install -m 755 ~/.config/crossfetch/bin/silk        ~/.local/bin/silk
install -m 644 ~/.config/crossfetch/bin/liturgy.py  ~/.local/bin/liturgy.py
install -m 644 ~/.config/crossfetch/bin/ricefx.py   ~/.local/bin/ricefx.py
install -m 644 ~/.config/crossfetch/bin/presets.py  ~/.local/bin/presets.py

Requires Python 3 (silk's 3D pieces also want numpy). A truecolor terminal is recommended; 256-color terminals work too via --color-mode 8bit (the Linux console and screen are detected and downgraded automatically). fastfetch is optional but is what --fetch and --sync-fastfetch are built around.

Usage

crossfetch [burst|ring|rain|both]   live animated dashboard
crossfetch --fetch [secs]           specs + glowing symbol
crossfetch --logo [symbol]          static rainbow art (for fastfetch)
crossfetch --sync-fastfetch         render themed fastfetch config
crossfetch --feast [id]             replay a feast animation on demand
crossfetch --setup                  interactive wizard -> config.json
crossfetch --list WHAT              presets | themes | symbols | feasts
crossfetch -p NAME [flags]          paint any of the above with a preset

Painting flags (combine freely with the commands above): -p/--preset, --c-set-l, --c-scale, --align, --bands, --color-mode, --symbol, --ascii-file, --backend, --theme. crossfetch -h has the one-line version of each.

Environment

Variable	Meaning
RICEFX_THEME	active theme (default rose-pine; auto light/dark otherwise)
CROSS_MODE	burst | ring | rain | both
CROSS_SYMBOL	which emblem to draw
CROSS_BURST	explicit accent pair (love,gold) — always wins over the season
CROSS_LITURGY	off disables all liturgical colouring
CROSS_FEAST	off disables feast emblems + one-shot animations only
CROSS_TIMEOUT	seconds before auto-exit (0 = until keypress)
CROSS_GLOW	seconds of --fetch shimmer
CROSS_FPS	frame-rate ceiling
CROSS_PRESET	like --preset (name, random, or #hex,#hex,...)
CROSS_COLOR_MODE	like --color-mode (rgb | 8bit)
CROSS_ALIGN	like --align
CROSS_BANDS	on — like --bands
CROSS_ASCII	like --ascii-file
CROSS_BACKEND	like --backend
NO_COLOR	skips every animation

--feast is an explicit replay: it deliberately ignores CROSS_LITURGY and CROSS_FEAST, which gate only the automatic behaviour.

Recipes

Everything is configurable per-launch or persistently (export in your shell rc):

RICEFX_THEME=gruvbox crossfetch            # same rig, gruvbox palette
RICEFX_THEME=catppuccin-mocha crossfetch --logo   # static art in another theme
CROSS_MODE=rain crossfetch                 # falling-trails animation instead
CROSS_SYMBOL=ichthys crossfetch --fetch    # fish emblem next to your specs
CROSS_BURST=iris,rose crossfetch           # pin your own colour pair year-round
CROSS_LITURGY=off crossfetch               # no church-calendar colouring at all
CROSS_TIMEOUT=5 crossfetch both            # auto-exit after 5s, alternate modes
crossfetch --feast pentecost               # replay the dove any day you like
crossfetch --sync-fastfetch                # re-skin fastfetch to current theme
crossfetch -p advent                       # burst in the wreath's candles
crossfetch --fetch -p marian --bands --align horizontal   # striped banner logo
crossfetch --logo -p '#8e1600,#f6a21d'     # your own two-color palette
crossfetch -p random --c-set-l 70          # surprise palette, lifted to 70%
CROSS_COLOR_MODE=8bit crossfetch --fetch   # full show on a 256-color terminal
crossfetch --ascii-file ~/my-art.txt       # your own art instead of an emblem

Set-and-forget example for ~/.zshrc:

export RICEFX_THEME="tokyo-night"   # theme for everything
export CROSS_MODE="burst"
export CROSS_GLOW="1.6"

Shell integration

The opening animation is one line in ~/.zshrc, guarded so it never runs in scripts or pipes (silk itself also refuses to draw when stdout is not a tty):

[[ -o interactive && -t 1 ]] && silk          # bloom by default, 3 s, any key skips

A zsh startup block regenerates the logo files and the themed fastfetch config once per day (or whenever RICEFX_THEME changes), tracked by a marker in ~/.local/state/crossfetch/last-render — so the static art follows the liturgical season with zero launch-time cost.

Tests

pytest tests -q

Covers silk (mode registry, the 256-glyph octant table, cycle state, every scene drawing off-screen, fade-out clearing, the flush style-reset rule, the no-tty no-op) and, for crossfetch, the Easter computus against known dates (2024–2030), season boundaries, feast hits and misses, theme-table completeness, emblem mask geometry, the feast one-shot gate, a byte-identical round-trip of the fastfetch template against a committed fixture — and, for the 2.1 layer: preset resolution and lightness math, the xterm-256 mapping, color-mode detection, alignment and banding, custom masks, the config round-trip, and CLI-level checks that flags, env twins and the config file all agree.

How the animations were made

bloom and cross were designed and written in one sitting on 7 September 2026 by Claude Fable 5.1 (Anthropic), working inside Claude Code on the author's Arch + Hyprland + kitty rig, with the author steering: the brief was "redesign the startup animation into something even better", then "an emerging cross". Claude chose the parametric rose and the point-cloud/z-buffer/octant approach, iterated each piece against real kitty screenshots (an offline render looked clean while the live terminal streaked gold, which is how the Grid.flush style-reset bug was found and fixed), profiled it up to 60 fps, and wrote the tests and this documentation. The commits carry its Co-Authored-By trailer. The author is happy for people to know an AI made something this over-the-top for a terminal splash.

Credits

• hyfetch — inspiration for the seasonal easter-egg pattern and the joy of a fetch tool with a personality.
• fastfetch — the system-info engine this decorates.
• Rosé Pine and the other theme palettes belong to their respective authors.

Soli Deo gloria.