PERSONAL•2026•Duccio Meconcelli

CaffeSaver

BashCHomebrewCLITerminal GraphicsANSI/ASCII ArtmacOS Caffeinate
§ 00 // ABSTRACT

An animated terminal screensaver collection and generative ASCII/ANSI art engine featuring native C visualizers (60 FPS), transparent JIT compilation, pure Bash fallback, and macOS anti-sleep protection.

CaffeSaver is a command-line collection of 18 animated terminal screensavers and generative ASCII/ANSI visualizers, combining real-time procedural graphics with native system anti-sleep integration.

Hybrid C & Bash Architecture

Terminal animations written purely in shell script quickly hit CPU and frame-rate ceilings when computing per-cell trigonometry or multi-octave noise. To maintain fluid rendering without sacrificing portability, CaffeSaver adopts a two-tier execution model:

  • Native C99 Engines at 60 FPS: Computationally intensive visualizers—such as rorschach-led, dunes, matrix, perlin-ascii, and perlin-pixel—are backed by C engines compiled with -O3 optimizations, sustaining 60 FPS at under 1% CPU usage.
  • Transparent JIT Compilation: On first launch, the runner inspects the host environment for clang, gcc, or cc and compiles the corresponding .bin executable automatically.
  • Zero-Dependency Bash Fallback: Every screensaver includes a pure Bash implementation (>= 3.2), guaranteeing out-of-the-box execution on minimal environments or systems without a C toolchain.
Rorschach LED terminal screensaver
rorschach-led — procedural symmetrical inkblots with ANSI LED palettes
Dunes 3D Perlin noise terminal screensaver
dunes — 3D animated topographic sand waves driven by Perlin noise
Matrix digital rain terminal screensaver
matrix — falling digital glyph streams with luminance gradients
Spirograph parametric curve terminal screensaver
spirograph — parametric hypotrochoid and epitrochoid curves

Terminal Safety & Anti-Sleep Integration

Running full-screen ANSI animations directly in an active shell session often corrupts scrollback history or leaves the cursor hidden after an abrupt interrupt. CaffeSaver isolates rendering through:

  • Alternate Screen Buffer Management: Enters and exits the terminal’s alternate buffer via tput smcup and tput rmcup, preserving the user’s prior shell output and prompt state.
  • Graceful Signal Trapping: Traps SIGINT, SIGTERM, and SIGWINCH to recalculate viewport dimensions dynamically on window resize and restore cursor visibility and SGR color state on exit.
  • Display Sleep Prevention: On macOS, execution is automatically wrapped with caffeinate -d to prevent display dimming and system sleep while a visualizer is active.
Rain storm terminal screensaver
rain — procedural downpour simulation with ground splash particles
Fireworks particle terminal screensaver
fireworks — multi-stage particle bursts in ANSI color

The gallery spans 18 modules ranging from classic retro-computing tributes (pipes, bouncing, stars, tunnel) to mathematical and cellular simulations (life for Conway’s Game of Life, rorschach, vibe, and speaky with cross-platform text-to-speech via macOS say, Linux espeak/spd-say, and Windows tts.vbs).

Packaged for distribution via Homebrew (brew install Duccioo/caffesaver/caffesaver), the repository also includes a module scaffolding generator (caffesaver --new <name>), Asciinema/GIF capture scripts, and an automated BATS test suite (The Jury) that validates CLI flags, fallbacks, and clean terminal teardown.

Resources