Docs

Aurora Glass, in full

The aurora command

A small command that ships inside the app. It writes into a file the app watches, so anything that can run a command — a script, a test run, a build, an AI agent — can set the bar’s state, colors or a message. In the app, Settings › Agents puts it on your PATH, and installing with Homebrew does it for you:

Terminal

brew install --cask gourneau/tap/aurora-glass

States

Command	What the bar does
`aurora busy`	Something is running: a light travels across the bar while it works.
`aurora wait`	Blocked on you: amber, slowly breathing brighter and dimmer.
`aurora ok` / `done`	The last thing succeeded: one ripple spreads out from the middle, then the bar goes calm.
`aurora fail`	The last thing failed: two quick blinks, then restless.
`aurora reset`	Back to normal.
`aurora ack`	Let the verdict showing go, and give the bar back to the look.

busy and wait expire after 15 minutes unless something refreshes them, so a session that is killed cannot leave the bar saying it is working; --hold 2h keeps one long job working. A verdict’s color holds for a while, playing again every few seconds so it is not missed, and then the look comes back: done after 45 seconds and failed after 30 minutes, or as set in Settings › States. aurora done --hold 30s sets it for one verdict, and aurora fail --until-ack holds one until it is acknowledged. Waiting wins over working, so an agent that needs you shows even while others are busy. A verdict’s color is picked to stand out from the look it lands on, and it moves differently too, so it reads on any look — a green look does not hide a success, nor a red one a failure.

How each state looks

Choose in Settings › States, or from a shell, where the choice becomes the app’s setting:

aurora style working chase      # comet, scanner, chase, flow, glint, rise, or bold: blaze, march, tide, tides
aurora style waiting bounce     # breathe, bounce, steady, or bold: throb, flood
aurora style done rise          # ripple, rise, glow, color, or bold: flood, burst
aurora style failed flash       # blink, flash, bounce, color, or bold: alarm, flood
aurora style failed-hold until-ack
aurora style rest on            # the bar is empty unless an agent is active
aurora style comes-in pour      # pour, sheet, drip, rise, flood, spread, beads or fade
aurora style goes-away fade     # the same choices, run backwards

aurora log lists what has reached the bar, newest last, and Settings › Activity shows the same.

Claude Code

aurora hooks --install adds the hook to ~/.claude/settings.json (or the one in $CLAUDE_CONFIG_DIR): additive, so every hook and setting already there is kept, with a backup written first, and a second run changes nothing. A file that is not valid JSON is left alone. aurora hooks --uninstall takes out only what it added, and plain aurora hooks prints what it would add. The hook runs aurora hook, which reads what Claude Code is doing and works the state out for itself. Several sessions at once are folded together: the bar is busy while any is working, amber if any is waiting on you, and shows a verdict only once they have all stopped. The hook can never stop a tool call.

In the app, When an agent needs you in Settings › Attention sets how loud that is: color only, tails of light that drop below the bar once when an agent starts waiting or something fails, or tails again every 20 seconds until it is answered.

Everything else

Command	What it does
`aurora palette #rrggbb…`	Override the colors with two to four of your own.
`aurora alert [seconds] [#rrggbb…]`	Flash, then go back to how it was.
`aurora set <channel> <value>`	Set a channel a look can `bind` to, such as `a0`.
`aurora say <text>`	Show a line of text, then let it go. `aurora say` on its own takes it down.
`aurora get` / `where`	Print the current state, or where it is kept.

Messages

aurora say takes a style:

--marquee scrolls through the bar (the default).
--fade shows, holds and fades.
--wash is poured into the aurora and carried off.
--visor drops down below the bar like a console.
--swell bulges out of the bar in a piece of the look’s own aurora, then sinks back in.

Halo and Campfire have no fluid to draw text into, so on those looks the first three show as a swell too.

And --for seconds, --font "Avenir Next", and --place left|right|middle|0.3 for where it goes.

Examples

npm test && aurora ok || aurora fail
sleep 1500 && aurora say "Time for a break"
aurora palette "#ff0055" "#ffcc00" "#00ddff"
aurora alert 4 "#00ff88"
aurora say "Deployed to staging"
aurora say "Build 412 is green" --swell --place right

Looks as files

Every look in Aurora Glass can be written out as a few lines of text, a .aurora file. Read it, change it, send it to someone. The built-in presets are written the same way, so Starlight and Fairy Dust are good ones to copy.

This is format 1 of the look language, last changed in Aurora Glass 0.1.171. Every value in the reference says which release it arrived in, and Language versions lists what each release changed.

Using one

Open Settings and go to Looks & Colors. The card named after the look on show is for that look:

Its options are sliders: the knobs the look offers, such as Starlight’s star count and shooting stars.
Edit This Look… opens Look Editor, with a slider for each thing that changes this look. Its Text side is the look as a file. Change it and press Apply. Anything the app could not read is listed under the editor, and the rest still applies. A few values have no slider and are set only here. Moving a slider writes the text afresh, so any comments in it go.
In the card’s … menu, Copy Look puts the look on the clipboard and Paste Look applies one someone sent you. Export… writes a .aurora file and Import… reads one.

You can also write one in the browser. The look editor runs the app's own renderer on the page, so the bar you see there is the bar you will get; when it looks right, press Copy and paste it into the app.

A whole file

Starlight, as the app writes it (shortened):

look    "Starlight"
author  "Aurora Glass"
about   "Nebula colors, a field of stars, and the odd shooting star."
format  1

palette "Starlight" #120d2e #6b2ea8 #e661b8 #85dbfa
set exposure      1
set saturation    1.5
set glow          1.6
set sparkle       0.5
set stars         1
set meteors       5
set curtains      0.6

option exposure      "Brightness" 0.3 2.5
option glow          "Glow"
option starcount     "How many stars"
option starspacing   "Star spacing" 0.4 3
option meteors       "Shooting stars a minute"

The lines

One statement per line. A comment starts with #, ; or //, except that # followed by a hex digit is a color.

The header

Line	Meaning
`look "Name"`	The look’s name.
`author "You"`	Who made it. Optional.
`about "One sentence."`	What it looks like. Optional.
`format 1`	Which version of these rules it was written for. A newer number still loads; this version reads what it knows.

`palette`: the colors

palette "Fairy Dust" #85339e #f273c7 #ffc7eb #fff2b3   # a built-in, by name and colors
palette #0b1d2e #1f8a70 #bedb39 #fd7400                # colors of its own
palette wallpaper                                     # follow the desktop

Four colors, lowest first. The first color is the color of the whole bar: on a band this short the bed is mostly that color and the others are the light on top. Design a palette from the first color outwards. Two or three colors are filled out to four.

`set`: a value

set exposure 1.2

Sets one of the look’s values, from the reference below. A value out of range is clamped, with a note. A file lists only what differs from a fresh look.

`option`: a knob the look offers

A look’s own settings, like the options screensavers used to have. Each appears as a slider on Looks & Colors, in the look’s own card.

option stars       "Star brightness"            # one of the look's values
option meteors     "Shooting stars" 0 20        # ...over a narrower range
option breathe     "Breathing" 0 1 0.3          # a value of the look's own

Named after a value in the reference, an option is that value as a slider, defaulting to what the look sets it to. Two numbers narrow the range; a third sets the value too.
Any other name is a value of the look’s own: option name "Label" min max default. A bind reads it by name.

option breathe "Breathing" 0 0.5 0.2
bind sparkle = 0.5 + breathe * sin(t * 0.4)

A slider for a value that a bind also drives does nothing, since the bind wins every frame. Expose a value of the look’s own and use it in the bind, as above.

`bind`: a value that moves

bind sparkle = 0.5 + 0.2 * sin(t * 0.4)

Recomputed every frame. A look’s binds run underneath the Moves with setting, and where both drive the same value Music wins, so it still reacts to music on any look.

Expressions use numbers, names, + - * / % ^, < and > (1 if true, 0 if not) and parentheses. Functions: sin cos abs sqrt floor, min(a, b), max(a, b), pow(a, b), clamp(x, lo, hi), lerp(a, b, t), smoothstep(e0, e1, x).

Name	What it is
`t`	Seconds since the app started.
`level bass mid treble beat`	The music, 0 to 1. Only while Looks & Colors › Moves with is set to Music, which the person chooses themselves.
`busy wait ok err`	What `aurora busy`, `wait`, `ok` and `fail` last said.
anything from `aurora set`	Whatever a script or program wrote.
your options	Each option of the look’s own, by name.

A name with no value reads as 0, so a bind on the music sits still until Music is on.

What a look can never do

A look file can never make the app ask for a permission. It has no way to name the Music visualizer, which taps system audio, or the menu-bar text mask, which needs Screen Recording, and neither can a bind or an option reach them. It cannot run code: no plug-ins, no files, no network, only the values below.

Reading is lenient

An unknown line, a typo, a value out of range or a newer file’s extras are noted and skipped, never fatal, so a shared look shows as much of itself as your version understands.

Reference: values

Color

Name	What it does	Range	Since
`exposure`	overall brightness of the aurora's light	0 – 6	0.1.45
`opacity`	how much of the bar the aurora covers, 0 to 1	0 – 1	0.1.45
`contrast`	tonal contrast: below 1 is softer, above 1 punchier	0.1 – 3	0.1.45
`saturation`	color intensity; the menu bar's glass mutes color, so above 1 is usual	0 – 3	0.1.45
`hue`	turns every color around the color wheel, 0 to 1	0 – 1	0.1.45
`cycle`	turns the colors around the wheel over time, per second	-0.2 – 0.2	0.1.45
`tint`	blends toward a vertical gradient — green low, violet high, as real aurora is	0 – 1	0.1.45
`huespread`	how many hues show across the bar at once; 0 puts it all on one color	0 – 0.5	0.1.45
`huescale`	how quickly the color changes along the bar	0.1 – 16	0.1.45
`huedrift`	how fast the color regions wander	0 – 1	0.1.45
`variety`	how different one curtain's color is from the next	0 – 3	0.1.45

Light

Name	What it does	Range	Since
`glow`	how much bloom surrounds the light	0 – 4	0.1.45
`glowspread`	how far the bloom spreads	0.2 – 6	0.1.45
`ambient`	an always-on floor of light, so the bar is never fully dark	0 – 0.4	0.1.45
`background`	how much of the palette's first color shows as the bar's base, under the light; a Brightness option moves it along with exposure	0 – 1	0.1.145
`additive`	how much the light adds to what is behind it rather than covering it	0 – 1	0.1.45
`cover`	how strongly the light covers what is behind it	0 – 3	0.1.45

Rays, sparkle and sky

Name	What it does	Range	Since
`rays`	strength of the vertical rays, 0 to 1	0 – 1	0.1.45
`raysharp`	how sharp-edged the rays are	0.1 – 6	0.1.45
`rayscale`	how many rays fit across the bar	0.5 – 30	0.1.45
`rayspeed`	how fast the rays drift	0 – 1	0.1.45
`rayflow`	how much the fluid drags the rays along with it	0 – 0.5	0.1.45
`detail`	layers of ray detail, 1 to 7: fewer is broader and calmer	1 – 7	0.1.45
`shimmer`	a fine flicker over the whole bar	0 – 2	0.1.45
`sparkle`	twinkling motes in the aurora	0 – 2	0.1.45
`motes`	how many motes across the bar	20 – 400	0.1.45
`twinkle`	how fast the motes twinkle	0.1 – 6	0.1.45
`stars`	stars in the dark between the curtains	0 – 1.5	0.1.45
`meteors`	shooting stars, roughly how many a minute	0 – 30	0.1.45
`starcount`	what share of the sky holds a star	0 – 1	0.1.47
`starspacing`	how far apart the stars are; 1 is the usual spacing	0.4 – 4	0.1.47
`startwinkle`	how deeply the stars twinkle; 0 holds them steady	0 – 2	0.1.47
`meteorlength`	how long a shooting star's tail is	0.3 – 3	0.1.47
`fairies`	fairy flights, roughly how many a minute	0 – 12	0.1.61
`engine`	0 the fluid simulation, 1 the glow: soft pools of color drifting along the bar, 2 fire: flames licking up from the bar's bottom edge; 1 and 2 are far lighter on the GPU	0 – 2	0.1.118
`fairytrail`	how long a fairy's trail of sparkles lingers	0.3 – 3	0.1.61

Motion

Name	What it does	Range	Since
`tempo`	the one pace control, over everything that moves	0.05 – 2.5	0.1.45
`speed`	how fast the fluid runs	0.02 – 4	0.1.45
`wind`	sideways drift of the fluid; negative blows the other way	-6 – 6	0.1.45
`shear`	how differently the top and bottom of the bar drift	0 – 8	0.1.45
`curl`	strength of the turbulence	0 – 10	0.1.45
`curlscale`	size of the turbulence	0.2 – 12	0.1.45
`curlspeed`	how fast the turbulence changes	0 – 1	0.1.45
`curloctaves`	layers of turbulence detail, 1 to 6	1 – 6	0.1.45
`vorticity`	how well swirls hold together	0 – 6	0.1.45
`buoyancy`	how fast the light rises	-3 – 4	0.1.45
`velfade`	how long motion lasts; nearer 1 keeps the fluid moving longer	0.9 – 1	0.1.45
`drift`	how fast the curtains travel along the bar	0 – 0.5	0.1.45

Curtains

Name	What it does	Range	Since
`emit`	how bright new curtains are	0 – 5	0.1.45
`emitspread`	how many curtains there are	0.3 – 14	0.1.45
`emitspeed`	how fast curtains are born and change	0 – 1	0.1.45
`emitheight`	how tall the band where new light is born is	0.01 – 1	0.1.45
`emitcenter`	where new light is born, from 0 at the bottom of the band to 1 at the top	0 – 1	0.1.45
`emitthreshold`	how much of the band stays dark between curtains	0 – 0.95	0.1.45
`curtains`	how much dark sky opens between curtains, 0 to 1	0 – 1	0.1.45
`fade`	how long color lingers; nearer 1 lingers longer	0.9 – 0.9999	0.1.45

Reference: palettes

Classic Aurora#0dff8c #26f2cc #598cff #d94df2
Solar Storm#ff4729 #ff9e33 #f2338c #8c1fd9
Arctic Ice#33f2ff #59a6ff #8c73ff #d9ebff
Nebula#591abf #d933b3 #408cff #ffcc73
Dragonfire#ffd940 #ff6614 #cc1433 #59054d
Bioluminescence#1affd9 #0db3f2 #7340ff #e673ff
Fairy Dust#85339e #f273c7 #ffc7eb #fff2b3
Pumpkin Spice#944214 #ed731f #d9944d #ffebcc
Starlight#120d2e #6b2ea8 #e661b8 #85dbfa
Rose Quartz#ff8cb3 #ffbf8c #b380ff #fae6f2
Flurry#ff338c #ffcc26 #26e6ff #8c40ff
Lavender Ribbon#7340b3 #c78cf2 #f2d9ff #66f299
SAR Arc#d91a1f #ff4d38 #730814 #ff8c66
Solar Wind#4df2ff #e6ffff #3380ff #1accd9
Sunset#ff5742 #ffa842 #db3d99 #6642c7
Pumpkin#ff5c08 #ff9e1a #851f9e #8cf226
Fir and Tinsel#1fa347 #eb1f29 #ffd16b #f5faff
Harvest#a34d21 #fa9e2e #bd2433 #ffdb8c
Halo#1a1a61 #3873ff #d952eb #ff8c47
Fire#380803 #d92e05 #ff850f #ffdb73
Ember#730f03 #f23808 #ff660d #ff9e38
River#08336b #1466c7 #40b8f2 #d1f2ff
Ocean#052b4d #05548c #14949e #b8f2eb
Monochrome Glass#a6c7f2 #d9ebff #738cbf #ffffff

Reference: the built-in looks

Northern Lights — Green curtains rolling into violet. Options: Brightness, Glow
Glacier Drift — Slow, wide, pale blue. Options: Brightness, Glow
Deep Nebula — Rich swirling color, slow bloom. Options: Brightness, Glow
Whisper — Barely there. For when you want it subtle. Options: Brightness
Flurry — The old OS X screensaver: bright hue-cycling streamers. Options: Brightness, Glow
Lavender Ribbon — A narrow ribbon of lavender light, with a green fringe below. Options: Brightness, Glow
Red Arc — A deep red arc, shifting slowly. Options: Brightness, Glow
Solar Wind — Swirling strands of cyan and white. Options: Brightness, Glow
Lava Lamp — Fat warm blobs, rising and folding. Options: Brightness
Plasma — Swirling patches of color, no rays at all. Options: Brightness, Glow
Sunset — Warm coral, with gold and dusk violet drifting through. Options: Brightness, Glow
Halloween — Pumpkin orange, guttering like a candle. Options: Brightness
Christmas — A fir-green bar, with holly red and tinsel in the bright parts. Options: Brightness, Glow
Thanksgiving — Deep russet and cranberry, drifting slowly. Options: Brightness, Glow
Fairy Dust — Rose and lilac, with gold motes that twinkle, and now and then a fairy flying by. Options: Brightness, Glow, Fairy dust, How many motes, Twinkle speed, Fairy flights a minute, Fairy trail
Pumpkin Spice — Pumpkin, caramel and cinnamon under whipped cream — slow, warm and cozy. Options: Brightness, Glow, Glints
Starlight — Nebula colors, a field of stars, and the odd shooting star. Options: Brightness, Glow, Star brightness, How many stars, Star spacing, Twinkle, Shooting stars a minute, Shooting star tails
Halo — Soft pools of blue, violet and amber drifting along the bar, with no fluid underneath: the lightest look on the GPU. Options: Brightness, Glow
Campfire — Flames licking up from the bottom of the bar, with sparks rising: no fluid underneath, light on the GPU. Options: Brightness, Glow
Fire Plasma — Plasma's swirling patches in ember, orange and gold. Options: Brightness, Glow
River — A blue current running along the bar, quick and streaked with light. Options: Brightness, Glow
Ocean — Slow, deep swells of navy and teal, with seafoam where they break. Options: Brightness, Glow
Rave — Loud, fast, hue-cycling. You asked for cool. Options: Brightness, Glow

Language versions

The language has a format number and the app has a release number, and the reference keeps track of both.

The format is the rules. Format 1 only ever grows: a value or a line can be added, but a name is never renamed, removed or given a new meaning. So a file you write today reads the same in every later release, and an older release reading a newer file skips the values it does not know and shows the rest. If a change ever cannot be made that way, the format goes to 2 and this format 1 reference stays published beside the new one.
The release is when something arrived. Each value in the reference says which release added it, so you can tell which versions of the app a file needs. If you share a look that uses fairies, anyone on 0.1.61 or later sees the fairies.

0.1.171 — tempo goes down to 0.05, a twentieth of Normal; it stopped at 0.15.
0.1.145 — An `option exposure` slider moves background too, up to half or double the look's own. A file reads as it always did: `set exposure` alone still moves only exposure. New values: background.
0.1.136 — `engine 2`: fire, flames licking up from the bar's bottom edge.
0.1.118 — New values: engine.
0.1.61 — New values: fairies, fairytrail.
0.1.47 — option lines: a look's own sliders, shown in This look. New values: starcount, starspacing, startwinkle, meteorlength.
0.1.45 — The language ships: look, author, about and format in the header, and palette, set and bind lines.

How it works

It is a real fluid simulation, not a video or an animated gradient: Jos Stam’s stable fluids, on a velocity grid sized to your display, solved every frame on the GPU in Metal. Each frame runs these steps in order:

Advection. Every cell traces backwards along the flow and samples where its fluid came from a moment ago. Semi-Lagrangian, so it stays stable at any timestep.
Curl-noise forcing. The wind is the curl of a noise field, which is divergence-free by construction, so turbulence goes in without inventing or losing fluid.
Vorticity confinement. A grid smears out small eddies; this measures the swirl being lost and feeds it back, which keeps the filaments sharp.
Pressure projection. A Jacobi solve for pressure, then its gradient is subtracted, making the field incompressible — why the aurora folds instead of piling up at one end.
Dye and light. The look’s color is carried by the flow and drawn with rays, bloom and the look’s own extras, like stars.

The bar on this website runs the same shaders, ported to WebGPU and checked against the app pixel for pixel. It paces itself to your display’s refresh rate, and stops when the screen sleeps or locks or a full-screen app is in front.