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, andperlin-pixel—are backed by C engines compiled with-O3optimizations, sustaining 60 FPS at under 1% CPU usage. - Transparent JIT Compilation: On first launch, the runner inspects the host environment for
clang,gcc, orccand compiles the corresponding.binexecutable 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.
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 smcupandtput rmcup, preserving the user’s prior shell output and prompt state. - Graceful Signal Trapping: Traps
SIGINT,SIGTERM, andSIGWINCHto 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 -dto prevent display dimming and system sleep while a visualizer is active.
The Visualizer Gallery & Tooling
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.