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
npx -y skills add martinemde/dotfiles --skill ghostty-shadersAssembled 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— nofsuffix on float literals in GLSL ESsaturate()— doesn't exist here; useclamp(x, 0.0, 1.0)- Negative input to
sqrt()orpow()— wrap withabs()ormax(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 derivingreferences/effects.md— grayscale, sepia, chromatic aberration, pixelate, hash noisereferences/glsl.md— GLSL ES 3.0 types, swizzling, math and texture builtins, control flow, structs, function rulesreferences/performance.md— focus gating, texture lookup reuse, cheap approximations, branch eliminationreferences/debugging.md— visualizing UV/time/focus state as color, isolating a failing effect behind a safe fallback, incremental build order