TimeTurner

A menu bar hourglass for the Mac. The sand drains over the current clock hour, and at the top of every hour the glass turns itself over.

The whole thing is drawn out of keyboard characters. The frame is = / \ ( ), the sand is . : ; , * o, and every grain is real: a falling-sand simulation drops them through the neck one at a time on the actual clock, so the top bulb takes the full hour to empty. The demo above is running at thirty-second hours; the real thing is slower and, honestly, better company.

There are two views of the same hour:

• The menu bar glass. A tiny hourglass that visibly drains across the hour and does a smooth 180 degree turn at the top of it. Click it for how long until the next turn, Launch at Login, and the window.

  

• The glass window. Resizable; the glass reshapes itself to fit, and the sand physically tumbles into the new shape rather than teleporting. A thin countdown under the glass shows how much of the hour is left. Close it and the menu bar keeps the time alone.

Nobody starts a pomodoro here. Turn on Pomodoro Mode and the hour becomes the classic grid: 25 minutes of work, 5 of break, twice per hour, turning at :00, :25, :30 and :55. Because 25 + 5 + 25 + 5 is exactly 60, the grid anchors to the clock like everything else here. It runs whether you are at your desk or not, and everyone running TimeTurner anywhere on earth is in the same slot right now. There is no timer to set, no state to lose, nothing to forget to start: you join the pomodoro already in progress, the way you would join the hour.

The app says so, too. Flip the mode on and joined work :30 to :55 floats up under the neck of the glass and dissolves into the sand, and the window title becomes the slot itself, so the timetable is always on display.

Work runs the usual sand. Breaks run different sand, wavy ~ and - grains, with a dimmed countdown and a lighter menu bar glass, so one glance says which side of the cycle the world is on. Two small grains under the countdown mark the hour's two pomodoros: done *, running o, still to come ..

Hover the menu bar glass and the whole hour lays itself out, one character a minute, in that same vocabulary: * spent, o where you are now, . still to come, ~ the break waiting for you. The menu already says how long until the turn in words. This says where in the hour you are, which is the part a sentence is bad at.

With Pomodoro Mode off the strip is one unbroken hour, ticked at the quarters, counting down to the turn.

Brown Noise in the menu plays a low, even rumble, generated live sample by sample, no audio files. It is there for masking: it covers the room so your head does not have to. And it follows the hour like everything else, running full while the work sand falls and dropping to a whisper during breaks, so you can hear which side of the pomodoro you are on with your eyes closed. No claims about magic frequencies here; brown noise simply keeps its energy down low, where it masks best and grates least over a long session.

No dock icon, no settings beyond Launch at Login, Pomodoro Mode, Brown Noise, Pin to Front, which floats the glass above every other window while you work, and Golden Sand, which tints the grains the amber of the app icon. About 900 lines of Swift, no dependencies. Builds with the Xcode Command Line Tools alone, so you do not need a 12 GB Xcode install to compile it.

Download TimeTurner.dmg, open it, and drag TimeTurner to Applications. It is signed and notarized by Apple, so it opens without any Gatekeeper warnings.

Or with Homebrew:

brew trust apeabody007/tap
brew install --cask apeabody007/tap/timeturner

The cask installs that same notarized dmg, so nothing is compiled on your machine. Homebrew 6 will not load a cask from a tap you have not trusted, which is what the first line is for.

Or build it from a clone:

./build.sh install

That builds TimeTurner.app, copies it to /Applications, and launches it. Turn on Launch at Login from the menu if you want it to always be there. Note that a local build ad-hoc signs, so macOS may ask you to approve it the first time.

./build.sh test

The clock lives in Sources/Clock.swift, apart from everything that draws, and it is nothing but arithmetic over a date. That is what lets the suite walk a whole hour in milliseconds instead of waiting one out: every boundary of the pomodoro grid, the fraction each slot has drained, the cycle number that makes the glass turn, and the sixty characters the hover panel is made of. CI runs them on every push, then builds the app and renders the icon frames headless.

./build.sh
./build/TimeTurner.app/Contents/MacOS/TimeTurner --demo

Demo mode compresses the hour into thirty seconds, so you can watch the sand drain and the glass turn over.

• Every grain lives in a character grid and obeys falling-sand rules: fall straight down if you can, otherwise tumble diagonally. Piles come to rest at a 45 degree angle, which is why the bottom builds a cone.
• The neck is a gate wired to the clock. It releases grains only as the hour says they are due, so the drain is not an animation of an hour, it is one.
• Real sand keeps a level surface. In a wide window the funnel walls slope shallower than the grains can tumble, so a leveling pass flows the top chamber's high spots to its lowest hollows until the surface sits flat.
• Resizing carries the sand along: each grain remembers where it sat as a fraction of its chamber and is set back down as close to that spot as the new glass allows, then the simulation settles the rest.
• The state is derived from the current time, so the hourly turn, waking from sleep, and a resize can all reseat the glass and it is never wrong.

The hour is small enough to fit in a prompt, if you tell Copilot the rules first. This repo ships those rules so the Copilot app and Copilot CLI stay inside the glass instead of inventing a start button.

• .github/copilot-instructions.md: the hour, the file map, and the constraints.
• .github/agents/sandkeeper.agent.md: a custom agent that keeps clock math in Clock.swift and cycle numbers honest.
• .github/skills/turn-the-glass/: build, test, --demo, and --render from the CLI.

In Copilot CLI, from the clone:

copilot --agent sandkeeper

Then ask it to turn the glass. ./build.sh test is how you know it did.

MIT