Live wallpapers for macOS that you write yourself: one Zig or Metal file per Desktop Space, running on the bare metal.

Our programs live in terminals and editors. We rarely get to see them run in their full glory, right there on the desktop. Argus fixes that: ignite a relativistic quasar behind your windows for a few milliseconds of GPU a frame, or really anything you can write a pixel for.

_{Cygnus A as the camera tilts to nearly edge-on. 120 FPS, rendered by the theme's own code. The other six are at the bottom.}

Argus is a bare-metal macOS app that gives every Desktop Space its own live theme. Swipe from one Space to the next and you swipe from a quasar to a night beach to a marbling bath.

A theme is a single source file in themes/:

• a Metal kernel (.metal) that answers "what colour is this pixel?" and runs on the GPU for every pixel at once, or
• a Zig file (.zig) that runs on the CPU through a tiny SDK, for simulations that are sequential and branchy.

Drop a file on a Space in the menu bar and Argus compiles it on the spot. Save an edit and it reloads within a second. There is no engine to learn, no asset pipeline, no framework: you get a pixel grid, a clock and a frame budget.

The engine itself is Zig 0.17.0 talking straight to the macOS frameworks, with no AppKit wrapper. It runs at 30 FPS, draws only the Spaces you can see, and does nothing at all while a full-screen app, the lock screen or a sleeping display covers them.

One quasar ships with the app, and it is real:

Cygnus A
Quasar: spinning (Kerr) black hole with its accretion disk, both computed.

Kerr is what the black hole is: the exact solution for a spinning black hole, which every real one should be. The quasar is what it is doing: feeding through a luminous disk. Every pixel's light is traced along exact Kerr light paths, the disk's glow comes from a physical model of a feeding quasar, and the approximations and artistic choices are named as such.

The flagship is themes/Cygnus_A.zig: the quasar hidden in Cygnus A, 2.5 billion Suns, feeding at about 1% of its limit, seen nearly edge-on. Why we think it is real, and how you can check:

• The light paths are tested against the exact answer. The traced edge of the shadow is compared with Bardeen's analytic curve at 766 points. The worst error is 8.9e-6 M on the CPU and 1.8e-5 M on the GPU, under 1/2000 of a pixel.
• Every checked claim is a record in a test ledger (make ledger): the claim, its reference, the measured value, the bounds and the command that produced it. Cygnus A has 49 asserted claims, and all pass: docs/cygnus_a_ledger.json.
• The headers say what is computed and what is chosen. Cygnus A's spin has never been measured, so its a = 0.9 is labelled a choice.

What you are looking at, how faithful each part is, how it was checked and how to reproduce it: docs/QUASARS.md. The full model, derivations and open questions for physicists: docs/QUASAR_MODEL.md.

Want your own? Cygnus A is generated from a template (make quasars); give it a mass, a spin and a feeding rate and grow your own plump one.

Every shipped theme is in themes/: drag any of them onto a Space.

curl -fsSL https://raw.githubusercontent.com/gke0op/argus/main/install.sh | sh

That's it: it downloads the latest release, checks it against the release's SHA-256, puts it in ~/Applications/Argus and opens it. Run it again to update. No Zig needed: every theme ships precompiled. The script is short; read it first if you like. Because it installs from the command line, macOS doesn't ask you to approve the app, which isn't notarized. Prefer the zip? docs/INSTALL.md has the steps. The download also carries the theme-writing guides: open WRITING_THEMES.md in the Argus folder, or open Claude Code there and ask for a theme (it finds the skills in .claude/skills/ on its own).

Themes are native code. A Zig theme becomes a dynamic library inside Argus, and a Metal theme runs on your GPU. Only run themes you trust. See SECURITY.md.

Requires macOS on Apple Silicon and Zig 0.17.0 (make zig installs it into .toolchain/, checksum-verified; brew install zig also works).

git clone https://github.com/gke0op/argus.git
cd argus
make zig                                  # install the pinned Zig 0.17.0 into .toolchain/
make run                                  # build Argus.app and start it
make stop                                 # quit it
make test                                 # run the test suites
make harness THEME=themes/Cygnus_A.zig    # verify and benchmark a theme headlessly
make harness THEME=themes/Tutorial_Tides.metal   # same, on the GPU for Metal themes
make check-themes                         # the harness on every theme
make release                              # dist/Argus-v<version>-macos-arm64.zip for a GitHub Release

Then click the eye in the menu bar. The Spaces strip shows one thumbnail per Desktop Space: drop a theme (or a picture) on any of them, and double-click one (or tap it with two fingers) to eject its theme and give that Space back to macOS. Pause with ⏸ (the eye closes while paused). The gear opens Settings: step a Space's theme (or go back to the macOS default), speed, frame rate (30 by default; 60, or 120 on ProMotion displays: smoother, but the cost grows with the rate), smooth swipes, live reload and open at login. Settings live in .argus_settings.conf next to Argus.app, one key=value per line.

The quickest way in is a Metal kernel:

kernel void argus_draw(constant ArgusFrame& f [[buffer(0)]],
                       texture2d<float, access::write> out [[texture(0)]],
                       uint2 gid [[thread_position_in_grid]]) {
    if (gid.x >= f.width || gid.y >= f.height) return;
    const float2 uv = argus_uv(gid, f);
    float3 col = 0.5f + 0.5f * cos(f.time + uv.xyx + float3(0, 2, 4));
    out.write(float4(saturate(col), 1.0f), gid);
}

1. Read the two tutorials, in order:
   • themes/Tutorial_Tides.metal: an aurora over a night sea in five small steps. No state, just "what colour is this pixel at this time?".
   • themes/Tutorial_Reef.metal: a reaction-diffusion reef that remembers, with a state texture that persists between frames.
2. Copy one to themes/<You>_<Name>.metal and run the harness:

   make harness THEME=themes/You_Name.metal

   It compiles the theme, runs it at 1920x1200 and at 320x200, checks for NaN/Inf and motion, times it, and writes a PNG.
3. Drop the file on a Space and keep editing; Argus reloads it when you save.

The full Metal contract (prelude helpers, state textures, data files, measured performance rules for Apple GPUs) is in .claude/skills/argus-metal-theme/SKILL.md. It is written so a coding agent can follow it, and it reads fine for people too. The guide keeps improving: every theme author, human or agent, leaves notes in .claude/skills/FIELD_NOTES.md, and the lessons go back into the skills.

CPU themes in Zig use themes/argus_theme_sdk.zig: a State struct with init, step, draw and deinit, one allocation at init and none after. Start from the skeleton in BENCHMARK.md §3, which passes the harness as it stands; themes/Cygnus_A.zig is a complete (and large) example. The contract and the harness gates are spelled out in BENCHMARK.md.

Measured on an M3 with 8 GB: one Space showing the theme at Argus's 30 FPS.

Argus with no theme: 13 MB, 0.2% CPU, no GPU. Hidden Spaces don't draw; each extra Space showing a theme adds memory (see BENCHMARK.md), and Spaces showing the same black hole share its traced image.

The full table, with back-to-back figures and memory on four Spaces, is in BENCHMARK.md.

Instead of benchmarks you'll never use: hand your agent one sentence and see how much creativity and metal affinity it has.

BENCHMARK.md is a self-contained prompt you can give any coding model: write one Zig 0.17.0 file that simulates something real and passes eight automated gates (compiles, one allocation, survives a 320x200 watchdog, respects the row stride, opaque pixels, no NaN, visible motion, under 16.7 ms a frame on one CPU core). A submission that passes is, at the same moment, a wallpaper you can drop on a Space. Run it zero-shot (paste the file into a chat) or agentic (an agent in a clone runs the harness itself); BENCHMARK.md has the steps for both.

Several earlier themes, now in the git history, started as answers to it, and the table in BENCHMARK.md records who wrote each one.

Argus started as a 24-hour build. Most of the code was written by AI systems directed by Ekmel Ozdemir: Argon (Google Gemini) wrote the first engine, the SDK, the harness and the benchmark; Claude Opus wrote most of the later engine work and the physics themes; 10+ agents from various model families contributed themes and species. The git history is the full record, and NOTICE.md credits each piece.

Coding agents: start at AGENTS.md, the map of the repository. Themes are the best way in. CONTRIBUTING.md covers the contract, the harness gates, the frame budget, honest headers and credit lines. If you think a physics claim is wrong, open a "physics claim challenge" issue with a source; that is the most useful report this project can get.

MIT, see LICENSE. Data files carry their own licences (the Orion Nebula data is CC0 and CC BY 4.0); see NOTICE.md.

Seven themes ship with the app. Each clip is 9 s at 120 FPS, drawn offline by the theme's own code on the app's GPU path, paced the way the app paces it. None of it is a screen recording.

Night Tide: a night on the coast; the flashes in the surf follow published dinoflagellate research.

Lizard Island: a diver's drift over a real Great Barrier Reef lagoon at metre scale.

Orion Nebula: the heart of M42, built from what telescopes measured of it; as the view swings round, the 3D shape behind the image appears.

Ebru Studio: a Turkish marbling bath worked by a restless random hand, under a glass ceiling of studio lights.

Tutorial Reef: the second tutorial, a reaction-diffusion reef that remembers between frames.

Tutorial Tides: the first tutorial, an aurora over a night sea in five small steps.