👁 LookAside

LookAside is a tiny, free and open-source eye-break reminder for macOS.

~172 KB app, ~11 MB RAM, no subscriptions, no tracking. A simple reminder to look away from your screen and rest your eyes.

LookAside lives in your menu bar and follows the 20-20-20 rule: every 20 minutes, it nudges you to look at something about 20 ft (6 m) away for 20 seconds. That tiny habit relaxes the eye muscles you strain by staring at a screen all day, and helps prevent dry eyes, headaches, and digital eye fatigue.

It's a single native Swift file — no Electron, no Python, no frameworks, no background services phoning home. It just quietly reminds you to rest your eyes.

Features

• Featherweight & native — a ~172 KB binary built with swiftc, using only AppKit. ~11 MB of memory, no runtime, no dependencies.
• Unmissable reminders — a clean floating HUD with a rotating message and an animated progress bar, shown over everything (not buried in Notification Center).
• 20 friendly messages — it never nags with the same line twice in a row.
• Bilingual — switch between English and Français from the menu; your choice is remembered. It defaults to your system language.
• Smart about sleep — when your display sleeps, the countdown freezes and resumes on wake, so you never get a stale reminder.
• Configurable & remembered — set the interval, the look-away time, and the alert sound (or turn it off) from the menu bar; every choice is saved and restored on the next launch.
• Private — no network access, no analytics, no accounts, no tracking. Ever.
• Starts at login — installs as a launchd agent and restarts itself if it ever crashes.

Requirements

• macOS
• Apple's Command Line Tools (they provide swiftc, the Swift compiler — free):

  swiftc --version        # already installed?
  xcode-select --install  # if the command above fails

LookAside is compiled from source on your own machine, so there's nothing to trust, notarize, or download as a prebuilt binary.

Install

git clone https://github.com/Snake-Angel/LookAside.git
cd LookAside
chmod +x install.sh uninstall.sh
./install.sh

That's it. LookAside compiles, starts immediately, and relaunches at every login. Look for the 👁 countdown in your menu bar.

To update after pulling new changes, just run ./install.sh again — it recompiles and reloads the agent.

Usage

Everything is in the menu-bar icon's menu:

Item	What it does
Next reminder in m:ss	Live countdown to the next break.
Settings → Interval	Time between reminders (5–60 min).
Settings → Look-away time	How long each break lasts (5–30 s).
Settings → Sound	Alert sound (Basso, Glass, Ping, Pop, Purr) — or Off to silence reminders.
Settings → Language / Langue	Switch the interface to English or Français (remembered across launches).
Test reminder	Preview a reminder right now.
Reset timer	Restart the countdown from the full interval.
Pause / Resume	Temporarily stop reminders.
Quit LookAside	Stop the app for this session.

Customizing the defaults

The menu changes apply to the current session. To change the values LookAside starts with, edit the three constants near the top of LookAside.swift and recompile (./install.sh):

let DEFAULT_INTERVAL = 20      // minutes between reminders
let DEFAULT_DURATION = 20      // seconds to look away
let DEFAULT_SOUND    = "Ping"  // Basso, Glass, Ping, Pop, Purr

Your settings — interval, look-away time, sound (including Off), and language — are saved automatically and restored on the next launch. The constants above are only the first-run defaults.

Useful commands

# Watch the logs
tail -f ~/.local/share/lookaside/lookaside.log
tail -f ~/.local/share/lookaside/lookaside.err

# Stop temporarily
launchctl bootout gui/$(id -u)/com.user.lookaside

# Start again
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.lookaside.plist

# Recompile after editing LookAside.swift
./install.sh

How it works

LookAside is one NSApplication accessory agent. A 0.1 s timer drives the menu-bar countdown and fires reminders; each reminder is an NSPanel HUD with a progress bar quantized to 5 % steps so it stays perfectly stable. The interface is fully localized through a small L10n string table, and display-sleep events freeze and resume the countdown.

For the full architecture — source layout, the HUD rendering, the localization design, the LaunchAgent, and the build process — see TECHNICAL.md.

Project structure

LookAside/
├── LookAside.swift           ← The entire app (Swift / AppKit, no dependencies)
├── com.user.lookaside.plist  ← LaunchAgent template
├── install.sh                ← Installer (compiles the native binary)
├── uninstall.sh              ← Uninstaller
├── icon.png                  ← Icon (menu bar + HUD)
├── assets/screenshot.png     ← README screenshot
├── README.md
├── TECHNICAL.md              ← Technical documentation
└── LICENSE                   ← PolyForm Noncommercial 1.0.0

Uninstall

./uninstall.sh

Removes the LaunchAgent and everything under ~/.local/share/lookaside/. Clean and complete.

Privacy

LookAside makes no network connections and collects nothing. No telemetry, no crash reporting, no accounts. It only ever reads/writes its own files in ~/.local/share/lookaside/ and one preference (your chosen language).

License

LookAside is free and source-available under the PolyForm Noncommercial License 1.0.0.

In plain terms: do whatever you want with it — use it, study it, modify it, share it — as long as it's not for commercial gain. You may not sell it, or use it (or modified versions of it) to make money. See LICENSE for the exact terms.

Credits

Made for tired eyes. Look away from the screen now and then — your eyes will thank you. 👁