clearfx 0.2.0

ClearFX
Because a blank screen is boring

Install · Usage · Animations · Create · Config

I got tired of just seeing my terminal text vanish instantly when I ran clear, so I built ClearFX. It swaps out the standard clear command for a quick, random terminal animation. One second you're clearing some messy logs, and the next you're watching a tiny city shut off its lights or some ASCII birds fly away.

It runs completely offline during playback, has a declarative package format so you can safely run community animations, and has a marketplace you can browse right from your terminal.

Installation

pip install clearfx

Shell Integration

To make your regular clear command actually use ClearFX, run:

clearfx setup-shell

It'll auto-detect what you're using (Bash, Zsh, or Fish) and show you exactly what it's adding before it does anything. It automatically backs up your config too, just in case.

If you need to force a specific shell:

clearfx setup-shell --shell zsh

Restart your shell or source your config file, and you're good to go!

If you ever want to go back to normal:

clearfx remove-shell

Usage

Play a random animation

clearfx play

Play a specific one

clearfx play aurora-fold

List what's available

clearfx list
clearfx list --builtin
clearfx list --community

Tweak the playback

clearfx play --duration 700       # Speed it up (ms)
clearfx play --fps 24             # Change frame rate
clearfx play --seed 42            # Get the exact same animation output
clearfx play --ascii              # Force ASCII mode
clearfx play --monochrome         # No colors
clearfx play --reduced-motion     # Accessibility mode

Emergency disable

If something goes wrong or you just need it off right now:

export CLEARFX_DISABLE=1

It'll completely bypass the animation and run a standard clear.

Animations

I've built 36 animations so far. Here's what's included:

Note: Built-in animations use fictional creator handles to demonstrate how marketplace attribution works.

Configuration

Settings live in your platform's standard config directory (like ~/.config/clearfx/config.toml on Linux).

clearfx config                      # Check current settings
clearfx config set duration_ms 900   # Change something

Example config:

enabled = true
duration_ms = 1100
fps = 30
reduced_motion = false
ascii_only = false
attribution_position = "auto"

Accessibility

ClearFX respects NO_COLOR for monochrome mode out of the box.

If you want simpler, gentler animations with fewer particles and no rapid flashing:

clearfx config set reduced_motion true

If your terminal doesn't like Unicode:

clearfx config set ascii_only true

Marketplace

You can grab designs other people have made:

clearfx search "space"
clearfx install aurora-fold
clearfx update

Creating Designs

I wanted to make it easy to build your own.

clearfx create my-animation
cd my-animation
# Edit src/design.py
clearfx preview .
clearfx validate .
clearfx pack .

Security Model

Running some random python code every time you clear your screen is a terrible idea. So, community packages use a .clearfx file format. It's just a ZIP archive with a declarative JSON scene definition.

There are no .py files, no arbitrary code execution, no shell scripts, and zero network access when playing. It's completely sandboxed.

Development Setup

If you want to poke around the code:

git clone https://github.com/random-unknown-username/clearfx.git
cd clearfx
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,client,recording]"
pre-commit install

To run the web marketplace locally for testing, the frontend code is included in the repo. Just start it up!

Troubleshooting

If things go weird:

1. Run clearfx doctor
2. If your terminal gets messed up if you hit Ctrl+C at the wrong time (it shouldn't, but just in case), type reset and hit enter.

License

MIT License.