agentsclimarketplace

Ghostty shaders

Skill martinemde/dotfiles/.claude/skills/ghostty-shaders

Write, debug, and optimize custom GLSL shaders for the Ghostty terminal. Covers Ghostty's Shadertoy-compatible GLSL ES 3.0 dialect, its terminal-specific uniforms (cursor position and color, focus state, event timestamps), the unsupported Shadertoy uniforms, focus-gated performance patterns, and adapting shaders from shadertoy.com. Use when creating or editing a .glsl file for Ghostty, diagnosing a shader that renders black or fails to compile, or setting custom-shader config.From its SKILL.md

Install
npx -y skills add martinemde/dotfiles --skill ghostty-shaders

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.6 KB, as published. Nobody here has run it

Ghostty Shaders

Ghostty compiles Shadertoy-compatible GLSL ES 3.0 (WebGL 2.0) with terminal-specific extensions. iChannel0 is the live terminal screen rather than an uploaded image, and the shader runs continuously while the terminal is visible — which makes performance and failure behavior matter more than they do on shadertoy.com.

A broken shader can lock you out

An invalid shader renders Ghostty as a black screen, including the window you would use to fix it. Keep a known-good shader to fall back to, build up from a passthrough rather than pasting a finished effect, and keep a non-Ghostty terminal reachable while iterating.

The compile failures that cause this are mostly a short list:

  • 1.0f — no f suffix on float literals in GLSL ES
  • saturate() — doesn't exist here; use clamp(x, 0.0, 1.0)
  • Negative input to sqrt() or pow() — wrap with abs() or max(0.0, x)
  • mod(x, 0.0) — division by zero
  • Uninitialized variables — no implicit zero
  • A function and a variable sharing a name

Configuration

# Single shader
custom-shader = ~/.config/ghostty/shaders/crt.glsl

# Multiple shaders chain: each one's output becomes the next one's iChannel0
custom-shader = ~/.config/ghostty/shaders/blur.glsl
custom-shader = ~/.config/ghostty/shaders/vignette.glsl

# Animation control
custom-shader-animation = true     # Default: animate when focused
custom-shader-animation = false    # Static: only render on terminal updates
custom-shader-animation = always   # Always animate (CPU intensive)

Entry point

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    // fragCoord: pixel coordinates (0,0 = bottom-left)
    // fragColor: output RGBA color
    vec2 uv = fragCoord.xy / iResolution.xy;
}

Uniforms

Standard Shadertoy uniforms Ghostty provides:

sampler2D iChannel0;           // Terminal screen texture (or previous shader output)
vec3 iResolution;              // [width, height, 1.0] in pixels
float iTime;                   // Seconds since first frame
float iTimeDelta;              // Seconds since last frame
int iFrame;                    // Frame count
vec3 iChannelResolution[4];    // iChannelResolution[0] == iResolution

Not supported — a shader referencing these won't compile:

float iFrameRate;
vec4 iMouse;
vec4 iDate;
float iSampleRate;             // N/A
float iChannelTime[4];         // N/A

Ghostty-specific extensions, which are what make terminal-aware effects possible:

vec4 iCurrentCursor;           // .xy = top-left corner, .zw = width/height
vec4 iPreviousCursor;          // Previous cursor position/size
vec4 iCurrentCursorColor;      // RGBA of current cursor
vec4 iPreviousCursorColor;     // RGBA of previous cursor
float iTimeCursorChange;       // Timestamp when cursor changed
float iTimeFocus;              // Timestamp when surface gained focus
int iFocus;                    // 1 = focused, 0 = unfocused

The timestamps are absolute, so animations key off the elapsed time:

float timeSinceCursorChange = iTime - iTimeCursorChange;
float timeSinceFocus = iTime - iTimeFocus;

Working shape

Nearly every shader here has the same skeleton — an unfocused early-exit to a plain passthrough, then the effect:

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    vec2 uv = fragCoord.xy / iResolution.xy;

    if (iFocus == 0) {
        fragColor = texture(iChannel0, uv);
        return;
    }

    vec4 color = texture(iChannel0, uv);
    fragColor = color;
}

That early exit does double duty: it's the cheapest performance win available, and it means a background window keeps rendering readable text even if the effect above it is wrong.

Adapting from Shadertoy

mainImage is already the right signature, so the work is in the differences: check the uniform list above for anything unsupported, strip iMouse interaction, add focus gating that Shadertoy has no concept of, and expect iChannel0 to be text rather than a photograph — effects tuned on a photo often destroy legibility. Optimize harder than the original, since a terminal shader runs all day rather than while a tab is open.

Testing complex math on shadertoy.com first is usually faster than iterating in a terminal you can render unusable.

References

  • references/patterns.md — focus-aware blur, focus transitions, cursor highlight and trail, CRT; the terminal-specific effects worth copying rather than deriving
  • references/effects.md — grayscale, sepia, chromatic aberration, pixelate, hash noise
  • references/glsl.md — GLSL ES 3.0 types, swizzling, math and texture builtins, control flow, structs, function rules
  • references/performance.md — focus gating, texture lookup reuse, cheap approximations, branch elimination
  • references/debugging.md — visualizing UV/time/focus state as color, isolating a failing effect behind a safe fallback, incremental build order

External

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.