clearfx 0.2.9

ClearFX
because a blank screen is boring as fuck

Install · Usage · Animations · Create · Config

ngl i got so sick of watching my terminal just instantly vanish every time i ran clear, so i made this. ClearFX literally hijacks ur standard clear command (or ls, or whatever u want) and drops a crazy terminal animation before wiping the screen. u could be looking at some messy ass logs and one second later ur watching a tiny city shut off its lights or some ascii matrix rain.

it runs completely offline, uses a super safe sandboxed .clearfx package format so nobody can run malicious code on ur machine, and has a whole marketplace u can browse straight from the terminal.

Installation

pip install clearfx

(if u already have it, just do pip install -U clearfx to update)

Shell Integration

to actually make your clear command use this, u gotta set up the shell hooks:

clearfx setup-shell

it auto-detects what ur using (bash, zsh, fish, or powershell) and injects the hook. don't worry, it makes a backup of your config first just in case.

after that, just restart your shell or resource it:

source ~/.bashrc

and if u ever wanna wipe it completely from your machine:

clearfx reset

Usage

play a random animation

clearfx play

wrap any command

want an animation to play every time you run ls or git?

clearfx wrap ls --anim aurora-fold

list what we got

clearfx list
clearfx list --community

tweak the playback

clearfx play --duration 700       # speed it up (ms)
clearfx play --fps 60             # buttery smooth
clearfx play --seed 42            # exact same output every time
clearfx play --ascii              # force ascii mode
clearfx play --monochrome         # no colors
clearfx play --reduced-motion     # accessibility mode (less crazy)

emergency kill switch

if something breaks or u just want it off right now:

export CLEARFX_DISABLE=1

Animations

i've built 36 built-in animations so far. they range from standard ascii art to full on rgb particle engines.

note: built-in animations use fictional creator handles to demonstrate how marketplace attribution works.

Configuration

all ur 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 rq

example config:

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

Accessibility

if ur terminal doesn't support crazy unicode or colors, u can force it:

clearfx config set ascii_only true
clearfx config set monochrome true

if u want simpler, gentler animations with fewer flashing lights:

clearfx config set reduced_motion true

Marketplace

u can grab designs other people have made from the community catalog:

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

Creating Designs

i wanted to make it insanely easy to build ur own animations using python.

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

(check out docs/CREATOR_SDK.md for the full sdk tutorial on how to write these)

Security Model

running random python code every time u clear ur screen is a terrible fucking idea.

so, community packages use a .clearfx file format. it's just a zip archive with a declarative JSON scene definition. there are ZERO .py files, ZERO arbitrary code execution, and ZERO network access when playing. it's completely sandboxed so u can install shit without worrying.

Development Setup

wanna mess with 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]"

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 to see wtf is wrong
2. if your terminal gets messed up (it shouldn't, but just in case), type reset and hit enter.

License

MIT License. do whatever u want with it.