Ghostty Blackhole

Landing page: s13k.dev/blackhole

A black hole floating inside your Ghostty terminal. It starts small and grows to swallow your screen, driven by whichever size mode you pick: a built-in pomodoro clock (grow through the hour, demand a break, leave you alone once you take it), or token mode, where it tracks how full Claude Code's context window is in real time.

Modeled on Eric Bruneton's black hole shader, which beam-traces Schwarzschild geodesics against precomputed lookup tables. A Ghostty custom shader is a single Shadertoy-style fragment pass with no custom textures, so the lookup tables are replaced by doing the physics live: every pixel near the hole integrates its own null geodesic through the Schwarzschild metric (the Binet-form acceleration a = -3/2 h² x/r⁵, which gives the exact photon bending). Your terminal contents play the role of the lensed background sky. Nothing below is painted on — it all falls out of the ray tracing:

What it renders

• The shadow — rays with impact parameter under b_crit = (3√3/2) r_s spiral through the horizon and come back black. Text near the edge is stretched into the photon ring before it disappears; text behind the hole really is gone.
• Gravitational lensing — escaped rays are projected back onto the terminal "sky" plane: text bends, magnifies, and shows the mirrored secondary image inside the Einstein ring. Far from the hole this hands off to the analytic weak-field deflection (α = 2r_s/b), so only pixels near the hole pay for the integration. Blue bends slightly more than red out there for a touch of chromatic aberration.
• Accretion disk — a thin Keplerian disk that a ray can pierce several times: the far side arcs over and under the shadow (the Interstellar look), and the photon-ring region shows higher-order disk images. Coloring is physical: a Shakura–Sunyaev temperature profile rendered as blackbody color, shifted and beamed by the relativistic factor g = √(1 − 1.5 r_s/r)/(1 − β·k̂) — the approaching side is blue-hot and boosted by g^N, the receding side dim and red.
• Photon ring — rays winding near the 1.5 r_s photon sphere pick up every disk crossing; the bright thin ring is emergent, not drawn.
• Lensed starfield — a faint procedural sky sampled with the bent ray direction, so stars smear into arcs around the hole (off by default — raise STAR_GAIN to enable).
• Gravitational time dilation — the disk pattern at radius r advances at the proper rate √(1 − 1.5 r_s/r), so the inner orbits visibly freeze; the whole disk also winds down as the hole grows heavier (DILATION_MIN).
• The hole drifts on a slow Lissajous path, confined to the upper part of the screen — the bottom WORK_AREA fraction (your prompt) is never distorted. Drift speed and reach follow its size: small and calm, big and restless.

Pomodoro mode

The break reminder is computed entirely inside the shader — no daemon, no shell hooks, nothing outside blackhole.glsl.

Shaders are stateless (no buffers persist between frames, and Ghostty has no custom uniforms), so a shader cannot remember when your work streak began. Instead the schedule is anchored to the wall clock via iDate:

• Cycle: the hole is always present while you work — it starts small at the cycle floor, grows over WORK_PERIOD_MIN (default 55 min), collapses back to small in the last minute, and stays small through BREAK_MIN (default 5 min). With 55+5 the peak hits at five-to-the-hour — a fixed, predictable rhythm.
• Typing detector: iTimeCursorChange tracks cursor activity in your terminal. Stop using it for IDLE_FADE_SEC (default 90 s) and the hole shrinks live, gone entirely after a few minutes of quiet — it never nags while you aren't actually working.

The trade-off of self-containment: the cycle won't re-anchor to a break you take at an odd time — it's an hourly bell, not a per-streak stopwatch.

Caveat: stock Ghostty (through 1.3) declares iDate but never populates it — it is always zero — so on current releases the wall-clock schedule doesn't advance: the hole sits at its small cycle-floor size and only the typing detector works. The full cycle comes alive once Ghostty wires iDate up (you can preview it today with TIME_SCALE, which runs off iTime instead). Token mode, the default, is unaffected.

Size modes

What drives the hole is selected by SIZE_MODE near the top of blackhole.glsl:

• MODE_POMODORO — the self-contained wall-clock schedule described above. Works standalone, no setup beyond the shader (but see the iDate caveat above).
• MODE_TOKENS (default) — the hole tracks Claude Code's context-window fill. Requires the bundled command (below).
• MODE_DEMO — a self-running 42-second showcase loop for recording demos: the hole grows from the corner seed to 100 % exactly as token mode would, while the disk look tours the tuner presets (Inferno → Gargantua → M87* donut → Face-on ember → Quasar → Blazar → Pure lens → Inferno), crossfading at each ~5 s slot boundary. Everything runs off iTime inside one compiled shader — no reloads, so a recording never hitches. Toggle it with ./demo-mode.sh on|off (which also reloads Ghostty); the cursor channel is ignored in demo mode, so a live Claude session can't disturb a recording. Record any full cycle — the loop restart is obvious (the hole snaps back to the corner seed).

Token mode

The hole reflects how full Claude's context window is, live:

• Empty context — a small hole in the top-right corner, sized to cover TOKEN_AREA_MIN (default 0.06 %) of the terminal area — the same felt size on any window shape.
• Filling up — it grows toward TOKEN_AREA_MAX (default ~3 % of the terminal at 100 % context — that's the shadow; the bright disk reaches ~3× past it, so it reads far bigger), moves faster, and its allowed roam box expands out of the corner — left and down — until it covers the whole playable screen above the work area; the hole wanders pseudo-randomly through all of it. The orbit is scaled to the box (never clipped — clipping would park it dead at the boundary), with margins that keep the shadow and bright inner disk on screen while it's small.
• /compact or a new session — snaps back to the corner seed.
• No Claude session running — the hole disappears entirely; you get a plain terminal.

How it works

Ghostty custom shaders take no custom uniforms — but they do get the cursor color (iCurrentCursorColor), and any program can set the cursor color with a standard OSC 12 escape. So the token count rides in on the cursor: a single bundled script, claude-token.py, is wired into Claude Code three ways and encodes the context fill into the low nibbles of an amber cursor color (#f5b000 empty → #f0bf0a full); the shader decodes it back out every frame. The fixed high nibbles plus a 4-bit checksum form a 16-bit signature, so a theme's own cursor color can't accidentally summon a black hole. No file is rewritten, nothing reloads, there is no recompile hitch — updates land on the next frame.

Level steps land smoothly, too: Ghostty bumps iTimeCursorChange on any cursor change including color and snapshots the old color into iPreviousCursorColor, so the shader decodes both and glides between the two levels — discrete updates read as continuous motion instead of popping the whole warp field. The glide time scales with the jump (TOKEN_GLIDE_*): 1 % ticks ease over 0.3 s, a 10 % jump takes 1 s, capped at 1.5 s.

A cursor color without the signature means "no session", so a bare install shows nothing until a live session encodes a real fill. (The shader's TOKEN_LEVEL define remains as a manual override for hand-testing a size; it only applies while the cursor carries no signal.)

Install token mode

Two pieces — the shader and the command:

1. Point Ghostty at the shader (see Install below) with SIZE_MODE MODE_TOKENS (the default).

2. Add this to ~/.claude/settings.json (adjust the path), then start a new Claude Code session:

   {
     "statusLine": {
       "type": "command",
       "command": "/path/to/blackhole_ghostty/claude-token.py"
     },
     "hooks": {
       "SessionStart": [{ "hooks": [{ "type": "command", "command": "/path/to/blackhole_ghostty/claude-token.py" }] }],
       "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "/path/to/blackhole_ghostty/claude-token.py" }] }]
     }
   }
   

This is global, so the hole reacts to any Claude Code session. A few notes:

• The cursor color is per-surface state, so every Ghostty split/window gets its own hole — concurrent sessions in different surfaces don't fight.
• Your cursor turns accretion-disk amber while a session is live (that is the data channel). Anything else recoloring the cursor gets overwritten at the next statusline refresh; a cursor without the signature simply means "no hole".
• Inside tmux/screen the OSC would need a passthrough to reach Ghostty — token mode is built for plain Ghostty sessions.
• To opt out, set SIZE_MODE MODE_POMODORO and remove the entries above.

Install

Requires Ghostty 1.3+ (for the cursor shader uniforms).

Clone the repo, then add to your Ghostty config (~/.config/ghostty/config or ~/Library/Application Support/com.mitchellh.ghostty/config on macOS):

custom-shader = /path/to/blackhole_ghostty/blackhole.glsl
custom-shader-animation = true

Reload the config (cmd+shift+, on macOS) or open a new window.

Tuning

Tuner app (macOS)

A native SwiftUI control panel in the spirit of Bruneton's demo page lives in tuner/: grouped sliders for every shader tunable, presets (Gargantua, Quasar, M87* donut, Blazar, Inferno, Zen, …), live two-way sync with the file, and every nudge hot-reloads Ghostty instantly via SIGUSR2.

cd tuner && swift run            # run it
./tuner/make-app.sh              # or bundle tuner/dist/Black Hole Tuner.app

Or just edit the constants at the top of blackhole.glsl and reload (cmd+shift+,).

Constants

At the top of blackhole.glsl. Radii are in Schwarzschild radii (r_s); the ISCO — the innermost stable circular orbit — is at 3 r_s.

N_STEPS (a #define) sets the geodesic integration budget per pixel; only pixels inside the ray-traced circle around the hole pay it. It's the main performance dial — that circle scales with the hole, so a big hole on a big high-DPI display is where frames go to die. Lower N_STEPS (and/or TOKEN_AREA_MAX) if the terminal gets sluggish at high context fill.

To eyeball any token level without a Claude session, drive the cursor-color channel by hand from a plain shell inside Ghostty: ./token-test.sh 0.42 holds a level, ./token-test.sh sweep runs 0 → 100 % over 25 s, and ./token-test.sh off hides the hole again. (Don't run it in a surface with a live session — its statusline re-emits the real level every refresh.) Note that a size glide only survives while the cursor holds still — any cursor move makes Ghostty snapshot previous = current, ending the transition early — which is why the hold mode lingers ~1.6 s before exiting back to the prompt.

For a fast debug loop, set TIME_SCALE to e.g. 100 to watch a complete pomodoro cycle — growth, collapse, break — in about 36 seconds, then set it back to 1. (It fast-forwards via iTime rather than the wall clock, so it works even on builds where iDate is stuck at zero.) The period knobs also accept fractional minutes if you'd rather shorten the real schedule itself.

Uniforms Ghostty gives custom shaders (1.3)

iResolution, iTime, iTimeDelta, iFrameRate, iFrame, iMouse (unused), iDate (wall clock — declared but stuck at zero through Ghostty 1.3, see the pomodoro caveat), iChannel0 (the terminal, iChannel1-3 unused), iCurrentCursor/iPreviousCursor (xy position, zw size), iCurrentCursorColor/iPreviousCursorColor, iCurrentCursorStyle/ iPreviousCursorStyle, iCursorVisible, iTimeCursorChange, iFocus, iTimeFocus, iPalette[256], iBackgroundColor, iForegroundColor, iCursorColor, iCursorText, iSelectionForegroundColor, iSelectionBackgroundColor. No persistent buffers between frames — shaders are stateless, which is why the pomodoro is wall-clock-anchored.

Three gotchas worth knowing if you hack on this:

• Ghostty's fragCoord y-axis runs top-down, opposite of the Shadertoy convention it otherwise follows.
• To trigger a config reload from a script, send SIGUSR2 — but find the PID with ps, not pgrep/pkill: those silently exclude their own ancestors, and Ghostty is an ancestor of any shell running inside it.
• Claude Code spawns statusLine/hook commands with no controlling terminal, so /dev/tty fails there — claude-token.py finds the session's pty by walking its ancestors with ps -o ppid=,tty=.

License

MIT — see LICENSE.

Inspired by Eric Bruneton's black hole shader (BSD-3-Clause). No code from that project is used here — this shader is an independent screen-space approximation written from scratch; the credit is for the idea and the physics it demonstrates.