EFFECTS.md

Effects

Effects are installable intro animations: they change the way the info appears when xfetch starts. The core renders the module lines, hands them to an effect binary (xfetch-effect-<name>), and plays the returned frames before settling on the final content. Example: the decrypt effect reveals each line from scrambled glyphs.

Effects are opt-in — without the binary installed, xfetch renders normally.

Install

From the effects repository (default: xfetch-cli/effects):

xfetch effects install decrypt

Or from a local path:

xfetch effects install ./effects/decrypt

Manage installed effects:

xfetch effects list      # list installed effects
xfetch effects remove decrypt

Binaries are stored in ~/.config/xfetch/effects/. Use --repo <url> (or the XFETCH_EFFECT_REPO env var) to install from a fork or mirror.

WebAssembly Effects

Effects can be compiled to WebAssembly and installed exactly like native ones. The core detects the binary header and runs the guest in the sandbox, enforcing the manifest limits through wasmtime epochs. Examples include a Rust core module (wasm-matrix) and a Python component (wasm-python-pulse).

xfetch effects install ./effects/wasm-matrix
xfetch effects install ./effects/wasm-python-pulse

Effects produce frames on stdout like any other plugin, so the same manifest and host-call rules apply. See WASM.md.

Configuration

{
    "effects": [
        { "plugin": "glitch", "duration_ms": 700, "fps": 30 },
        { "plugin": "decrypt", "duration_ms": 1500, "fps": 30 }
    ]
}

The effects value accepts a single object or a list; a list plays the effects in sequence. Each effect receives the same rendered lines and settles on them, so chaining glitch → decrypt flows seamlessly into the final fetch.

Field	Type	Default	Description
plugin	string	—	Effect name (binary xfetch-effect-<name>).
style	string	none	Effect-specific style selector, passed to the effect.
duration_ms	number	effect default	Total animation length in milliseconds.
fps	number	effect default	Frames per second.
args	object	none	Free-form parameters passed to the effect.
timeout_secs	number	30	Safety net: kills the effect process if it runs longer. Unset uses the 30 s default; 0 disables the cap.

Writing an effect

Effects speak the xfetch-effect-api protocol (see xfetch-cli/api): read an EffectRequest from stdin (the rendered lines plus style/duration_ms/fps/args) and write an EffectResponse with a non-empty list of { delay_ms, lines } frames. The last frame should reach the final content.

Effect implementations live in xfetch-cli/effects (one crate per effect, binary xfetch-effect-<name>).