dotfiles: Skill for Claude Code

Ghostty Shader Development Skill

Overview

This skill provides comprehensive guidance for creating and editing custom shaders for Ghostty terminal. Ghostty uses Shadertoy-compatible GLSL ES 3.0 (WebGL 2.0) shaders with additional terminal-specific extensions.

When to Use This Skill

• Creating new Ghostty shaders from scratch
• Modifying existing Ghostty shaders
• Debugging shader compilation issues
• Optimizing shader performance for terminal usage
• Implementing focus-aware shader effects
• Working with terminal cursor animations

Critical Safety Notes

SHADER SAFETY: Invalid shaders can render Ghostty completely unusable (black screen). Always:

1. Test shaders incrementally with simple effects first
2. Keep a backup of working shaders
3. Provide fallback behavior (especially for unfocused states)
4. Initialize all variables explicitly
5. Validate shader compilation before deployment

COMMON PITFALLS TO AVOID:

• 1.0f notation (use 1.0 only - no 'f' suffix)
• saturate() function (use clamp(x, 0.0, 1.0))
• Negative values to sqrt() or pow() (wrap with abs() or max(0.0, x))
• Division by zero in mod(x, 0.0)
• Uninitialized variables (always initialize!)
• Function names matching variable names

Ghostty Shader Architecture

Configuration

custom-shader = /path/to/shader.glsl
# In ghostty config
custom-shader-animation = true # true (focused), false (static), always

Multiple shaders chain together - output of one becomes iChannel0 input of the next.

Shader Entry Point

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

    // Typical UV calculation
    vec2 uv = fragCoord.xy / iResolution.xy;

    // Your shader code here
}

Standard Shadertoy Uniforms

Available in Ghostty

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