What It Does
Lookout sits silently in the menu bar as a binoculars icon. When something on GitHub needs you, the icon switches to a red-tinted filled variant and slowly pulses until the items are resolved.
Click the binoculars to drop a popover with the items grouped by repository — each row showing the kind, title, and how long ago it was updated. Click any row to open it on github.com. The popover’s footer has a Mark all read button that calls GitHub’s notifications API to clear unread state in one sweep.
Three Sources, One Inbox
Lookout polls three GitHub queries concurrently and dedupes the results into a single list:
| Source | What it covers |
|---|---|
| Notifications API | The unified feed: mentions, review requests, assigns, comments, state changes, CI activity on subscribed threads |
| Review requested | Open PRs awaiting your review |
| Failing CI on your PRs | Your own open PRs with at least one failing check |
Polling runs at the interval GitHub itself recommends (usually 60 seconds), and uses If-Modified-Since so untouched polls don’t burn rate-limit budget. Polling pauses when the system sleeps and resumes — with an immediate refresh — on wake.
Setup
Lookout needs a classic GitHub Personal Access Token. Fine-grained PATs do not work with GitHub’s Notifications API and are rejected by the server.
- Create a token at github.com/settings/tokens/new with these scopes:
notifications,repo(orpublic_repoif you only watch public repositories),read:user. - Launch Lookout. A setup sheet asks for the token. Paste it and click Save.
- The token is validated against
GET /user, then stored in your macOS Keychain (servicecc.jorviksoftware.Lookout). It is sent only toapi.github.com.
To replace the token later: right-click the menu-bar icon → Re-enter GitHub Token…
Controls
| Action | Result |
|---|---|
| Left-click binoculars | Open the items popover |
| Right-click binoculars | Standard Jorvik menu (About, Refresh, Re-enter Token, Check for Updates, Settings, Quit) |
| Click an item row | Open it on github.com |
| Refresh button | Force an immediate poll |
| Mark all read | Clear every GitHub notification (calls PUT /notifications) |
Settings
Right-click the icon and choose Settings… to configure:
- Menu bar icon pill — optional grey background for stronger contrast on busy or wallpaper-tinted menu bars (off by default)
- Launch at Login — start automatically when you log in
Auto-updates are handled by Sparkle. Use the “Check for Updates…” menu item to check on demand; Sparkle’s prompt offers an “Automatically download and install updates in the future” checkbox the first time an update is available. Lookout checks for new versions automatically once a day in the background.
Installation
Two formats on every release — both signed and notarised, pick whichever suits:
- Installer (
.pkg) — recommended for first-time installs. Double-click to run; macOS Installer places the app in/Applicationswithout quarantine or App Translocation. - Download (
.zip) — unzip and dragLookout.appto your Applications folder.
After installation, launch Lookout — a binoculars icon appears in the menu bar. On first launch a sheet asks for your GitHub token (see Setup above).
Privacy
- No telemetry. No analytics. No ads. No subscriptions.
- The PAT lives in your macOS Keychain and is never written to disk in plain text.
- Network traffic goes only to
api.github.com.
Building from Source
Lookout is a Swift app with no dependencies beyond macOS system frameworks. No Xcode project is required.
- Clone the repo:
git clone https://github.com/PerpetualBeta/Lookout.git - Run
gmake build - Launch with
open .build/Lookout.app
gmake build drives the shared release.mk pipeline — compiles the Swift sources with swiftc, links against Cocoa, SwiftUI, ServiceManagement, and Security, and signs the bundle with the Developer ID identity.
Requirements
- macOS 14 (Sonoma) or later
- A GitHub classic Personal Access Token (see Setup)