Skip to content

Pause effects from a program

Use a hold to turn off selected effects while a pane is focused. Switching away removes its influence; switching back restores it.

From a shell or script

gft effects hold demo --off all --on cursor_trail --until pane
gft effects release demo
gft effects list

This keeps effects off, except the cursor trail, until released or the pane closes. Reusing a hold ID replaces that hold.

Option Use
--off sparks,camera Disable named effects or groups
--on cursor_trail Keep an effect on despite other holds in this pane
--target %12 Manage another pane in the workspace
--osc Print a terminal sequence; useful over SSH
gft effects release Release every hold in the pane

--on cannot override context rules or the Off effect profile.

Scopes

--until Hold ends when…
process (default) Foreground process group changes, such as an editor exiting
pane Pane closes or terminal resets
clear Explicitly released

Every scope can be released manually. A short shell command usually needs --until pane to keep its hold after the command exits.

Effect names

Selector Effects
all Everything
camera Zoom, tilt, drift, shake, depth of field
sheet Curvature, ripple, splash, gloss, shadow
typing Camera, curvature, ripple, splash, lighting, pane zoom
Individual names sparks, cursor_trail, pane_zoom, weather, lighting, tab_switch, session_switch

Use dotted names such as camera.tilt or sheet.ripple for one effect. These match context-rule selectors.

Editor and keyboard integration

graffitty.nvim exposes require("graffitty.effects") with hold, release, watch, and setup. Use editor callbacks for mode- or filetype-specific holds.

Bind ReleaseEffectHolds to clear all holds in the focused pane. Prefix, R settles motion once; it does not release holds.

The filetree can place its own hold while open; see Filetree.

Terminal protocol

Skip this section when invoking gft or the editor integration.

For integrations that cannot invoke the CLI:

ESC ] 4723 ; effects ; hold=<id> ; off=<names> [; on=<names>] [; until=<scope>] BEL
ESC ] 4723 ; effects ; release=<id> BEL
ESC ] 4723 ; effects ; release BEL

Inside tmux, wrap the sequence in DCS passthrough. gft effects hold ... --osc wraps it automatically; see pane claims. Unknown effect names or malformed sequences are ignored.

The server shares holds with connected clients. Holds do not rewrite world settings or profiles. For implementation checks, use tools/test_session_effects.py --case adaptive.