arrow_back Projects
PERSONAL // 2026 • Duccio Meconcelli

CaffeSaver

Bash C Homebrew CLI Terminal Graphics ANSI/ASCII Art macOS Caffeinate
code Code launch View Resource
auto_awesome 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.

Overview

I developed CaffeSaver to turn idle terminal sessions into a lightweight, aesthetic visual playground. While terminal art and command-line screensavers have a long history, they often suffer from high CPU usage, stuttering frame rates, or complex dependencies. CaffeSaver bridges this gap by combining native C performance with the instant portability of Bash and built-in macOS display power management.

The project features a curated gallery of 18 animated screensavers—ranging from Perlin noise terrains and Rorschach inkblots to matrix rain, spirographs, and cellular automata.

Hybrid architecture and performance

To achieve smooth rendering without exhausting system resources, computationally intensive visualizers (such as dunes, matrix, rorschach-led, perlin-ascii, and perlin-pixel) feature dedicated native C engines compiled with -O3 optimizations. These engines deliver steady 60 FPS animation with under 1% CPU utilization.

The execution model uses a transparent just-in-time (JIT) compilation pipeline:

  • When a screensaver is launched, CaffeSaver detects available system compilers (clang, gcc, or cc) and compiles the binary on first execution.
  • If no C compiler is present in the environment, the runtime automatically falls back to a pure Bash implementation, ensuring zero-dependency execution across any Unix-like environment.

Terminal safety and system integration

Screensavers should never corrupt the active shell state or leave visual artifacts after exit. CaffeSaver implements several core safeguards:

  • Alternate screen buffer: Uses tput smcup and tput rmcup to render artwork on a separate virtual screen, restoring the user’s scrollback history, command line, and cursor state upon exit.
  • Graceful signal handling: Traps SIGINT (Ctrl+C), SIGTERM, and SIGWINCH (window resizing) to reliably restore terminal cursor visibility and ANSI attributes.
  • Anti-sleep protection: Automatically wraps execution with caffeinate -d on macOS, keeping the display awake and preventing screen dimming while the animations run.
  • Cross-platform voice synthesis: Includes a multi-platform text-to-speech abstraction layer (library/library-of-voices.sh) supporting macOS say, Linux espeak/spd-say, and Windows TTS.

Packaging and developer tooling

CaffeSaver is packaged for distribution through Homebrew with a custom formula and tap (brew install Duccioo/caffesaver/caffesaver) as well as a standalone installer script.

The repository also provides comprehensive tooling for contributors:

  • A built-in CLI scaffolding generator (caffesaver --new <name>) that initializes new screensaver modules with boilerplate signal traps and metadata.
  • An automated testing suite dubbed The Jury, implemented with BATS (Bash Automated Testing System) to validate CLI flags, fallbacks, and rendering behaviors.
  • Media recording scripts for generating Asciinema captures and animated GIF previews.

Resources