fake-warp.hx

fake-warp.hx is a Helix Steel plugin that triggers terminal cursor animations by briefly flashing an intermediate cursor shape whenever a block cursor is involved.

Helix's block cursor is rendered as a styled cell rather than the native terminal cursor, so the terminal's blink/warp animation never resets on its own. This plugin forces a shape transition to make the terminal redraw its cursor animation. Particularly useful with Ghostty's custom shader cursor animations (e.g. ghostty-cursor-shaders⁠).

It hooks into two events:

• mode switch — if either the outgoing or incoming mode uses a block cursor, flash an intermediate shape (bar or underline) for a short duration; when switching between two block modes, it flashes two intermediate shapes so the transition still feels confirmed
• cursor movement — if the current mode uses a block cursor, briefly flash a non-block shape

Requirements

• Helix built with the Steel event system. See STEEL.md⁠.

Installation

Install the package with Forge:

forge pkg install --git https://github.com/Xerxes-2/fake-warp.hx.git

Then load and install it from your Helix init.scm:

(require "fake-warp/fake-warp.scm")
(install-fake-warp!)

Both hooks are enabled by default. Pass #f to skip a hook you don't need:

; Skip mode-switch animation, keep cursor-movement animation.
(install-fake-warp! #:mode-switch #f)

; Only mode-switch, no cursor-movement animation.
(install-fake-warp! #:selection-change #f)

Notes

• Cursor shapes are read automatically from the live editor config on first use — no manual configuration needed.
• The intermediate shape is shown for 40 ms by default, which is enough for the terminal to render one frame at 60 Hz or above.
• The plugin guards against re-entry so rapid events do not stack animations.