Flames

Flames is a native macOS menu-bar app that renders a transparent, click-through fire line along the bottom of every display. System-wide CPU activity makes the fire react quickly; macOS thermal pressure adds a slower heat signal during sustained workloads.

Run from Terminal

Clone the repository and launch Flames with one command:

git clone https://github.com/sensahin/flames.git
cd flames
./run.sh

This builds and opens the app without opening the Xcode project or using the Xcode interface. A full Xcode installation is currently required for Apple's command-line compiler and macOS SDK. To build without launching, run ./scripts/build.sh.

The flame icon's menu shows live CPU load, thermal state, flame energy, and measured FPS. It can hide the overlay, change sensitivity, or open Tune Flames… for live Metal controls. Quit the app from the same menu.

Why it does not show a temperature in degrees

macOS has no supported public API for numeric CPU temperature. Reading the SMC directly is private and hardware-dependent, while powermetrics requires privileges. Flames therefore uses supported signals: aggregate CPU tick deltas and ProcessInfo.thermalState. This keeps the app portable across Intel and Apple-silicon Macs and avoids requesting elevated access.

Project notes

• Requires macOS 13 or later and a Metal-capable Mac.
• The app is an accessory app, so it appears in the menu bar instead of the Dock.
• It targets 60 FPS at logical-point resolution—half Retina resolution—and upscales the naturally soft procedural field.
• During fair, serious, and critical thermal pressure it drops to 45, 30, and 20 FPS respectively so the visualizer does not worsen the condition it shows.
• At effectively zero flame energy it pauses automatically, using hysteresis to avoid repeatedly starting and stopping near the threshold.
• Hiding the overlay pauses Metal rendering instead of drawing invisibly.
• The overlay ignores mouse input and joins all Spaces, Stage Manager sets, and eligible full-screen Spaces.
• Domain-warped three-octave signed fBm, a continuous blackbody color ramp, detached wisps, procedural embers, and self-refraction require no downloaded images or screen recording permission.
• Each transparent Metal surface spans its full display. The shader keeps the fire near the bottom and reaches zero alpha well inside that surface, so no visible content can be clipped by a horizontal window boundary.
• project.yml is the source of truth for the generated Xcode project. A generated project is checked in, so XcodeGen is only needed after editing the project specification.

Deterministic visual QA

The three debug states are simulations, not fake temperature readings:

.build/Build/Products/Release/Flames.app/Contents/MacOS/Flames --demo-heat low
.build/Build/Products/Release/Flames.app/Contents/MacOS/Flames --demo-heat medium
.build/Build/Products/Release/Flames.app/Contents/MacOS/Flames --demo-heat high

Demo launches always use the standard tuning, balanced sensitivity, and a visible overlay. A process lock refuses a second graphical instance so QA captures cannot accidentally stack multiple flame layers.

The tuning panel exposes turbulence, motion speed, white-core heat, opacity, maximum height, and ember density. It also reports measured FPS, GPU time per frame, and estimated renderer duty.

For repeatable visual and performance inspection, the panel can be opened at launch and the app can print a timed renderer report before exiting:

.build/Build/Products/Release/Flames.app/Contents/MacOS/Flames \
  --demo-heat high --show-tuning --performance-report 8

Renderer duty estimates the fraction of each second occupied by this app's Metal command buffers. It is intentionally not presented as whole-system GPU utilization, which macOS does not expose through the app's public APIs.

To audit the Mach host send-right balance for ten minutes:

.build/Build/Products/Release/Flames.app/Contents/MacOS/Flames --mach-port-soak-test 600

License

Flames is available under the MIT License.