You start a long Claude Code task and walk away. Ten minutes later your Mac sleeps, the run dies, and you come back to nothing. So you set sleep to Never, forget to change it back, and your laptop cooks itself for a week.
Belay is a macOS menu bar app that fixes exactly that, and nothing else. It watches your local coding agents, holds the Mac awake only while one is genuinely working, and hands sleep straight back the moment everything goes quiet. Your System Settings are never touched.
The trade-off it is tuned around is lopsided on purpose: sleeping sixty seconds too early kills a long run silently and wastes an evening, while staying awake sixty seconds too long costs nothing at all.
| 🎯 Zero setup | Claude Code is detected automatically. Nothing to configure, no key to paste. |
| 🔌 Every agent | Codex, Gemini CLI, Cline and Aider ship as presets. Anything else: watch a folder, watch a process, or send a webhook. |
| 🛡 Never stuck | Every hold expires by itself after 120 seconds unless Belay re-arms it. Crash it, force-quit it, kill it, and your Mac is back to normal within two minutes. |
| 🔋 Your rails | A cap on continuous awake time, a battery floor, and release on sleep, quit and mode change. |
| 👀 Subagents too | Parallel subagents are counted as the one session they belong to, not as noise. |
| 📊 Time saved | It counts the time it held while you were away from the keyboard, which is the only time that was ever at risk. |
| 🔒 Stays local | No account, no telemetry. One daily version check, carrying nothing about you, and one switch turns it off. |
| 🌍 Multilingual | English, Русский, Deutsch, Español, Français, Italiano, 简体中文. |
1. Download Now
2. Open the disk image and drag Belay into Applications.
3. That is the install. Launch it and it lives in the menu bar.
The app and the disk image are both signed with a Developer ID and notarized by Apple, and both carry a stapled ticket, so the first launch works with no network and without the right-click-Open dance.
Other ways to install
brew install --cask perfectoweb/tap/belaybrew upgrade keeps it current afterwards. It installs the same signed,
notarized disk image the button above gives you, and Homebrew checks its
SHA-256 before it opens it.
The cask lives in our own tap rather than in homebrew-cask itself. Homebrew's main cask repository has a notability bar. A project needs a certain number of stars, forks or watchers before it is accepted, and Belay has not cleared it yet. Same command shape, one extra word.
⏳ Waiting on review. The sandboxed build exists and is what the App Store target builds; the listing is not up yet.
No Apple Developer account needed:
git clone https://github.com/PerfectoWeb/Belay.git && cd Belay
scripts/build-local.sh
open build/Belay.appNeeds Xcode 16 or later, plus xcodegen, swiftlint and swift-format from
Homebrew. The result is ad-hoc signed, which means it runs on your Mac and will
not open on anyone else's without a right-click.
spctl -a -vvv -t install /Applications/Belay.app
codesign -dv --verbose=2 /Applications/Belay.appYou should see source=Notarized Developer ID and team VSY2EB4Y9E.
1. Launch it. One welcome screen explains what Belay reads. Then it lives in the menu bar. There is no Dock icon and no window.
2. Leave it in Auto. That is the whole product. Belay holds the Mac awake while an agent is working and lets it sleep when nothing is.
| Mode | What it does |
|---|---|
| 🪄 Auto (default) | Awake if and only if an agent is working |
| ☀️ Always On | A better caffeinate, with the same safety rails |
| 🌙 Off | Belay holds nothing |
3. Left-click the menu bar icon for the panel: what is running, for how long, and, when Belay is not holding, the reason in plain language. Right-click for a compact menu.
4. Check it yourself, any time. Belay never asks to be trusted:
pmset -g assertions | grep "pid $(pgrep -x Belay)("You will see the assertion, a plain-English reason, and how long it has left.
Adding a tool Belay has never heard of takes one line. If it can run a shell command, it can talk to Belay. See
docs/HOW-IT-WORKS.md.
My Mac still went to sleep
Open the panel. It always says why in plain language. The usual answers are the battery guard, the maximum awake time, or that Belay did not think anything was running. If it is the last one and your agent was working, that is a bug worth reporting: include the tool and the macOS version.
It does not work with the lid closed
Nothing can make it. An idle-sleep assertion does not keep a MacBook awake with the lid shut. macOS enters clamshell sleep unless the machine is on AC power with an external display attached. Belay will not pretend otherwise.
My screen still turns off
That is intentional and saves real power. Belay prevents system sleep; the machine underneath keeps working. There is a setting to keep the display awake too, off by default.
Belay does not see my agent
Claude Code needs no setup. Everything else is configured in Settings ▸
Providers: switch on a preset, or point the folder watcher at wherever your
tool writes while it works. If your tool can run a shell command, the webhook in
docs/HOW-IT-WORKS.md is
one line.
It says "needs setup"
A preset's path did not exist on your machine. Presets are configuration, not code, so open Settings ▸ Providers and correct the path. A wrong preset costs one edit, never a release.
Something else
Open an issue. The macOS version
and the agent you were running are the two things that make a report
actionable. docs/QA-CHECKLIST.md lists what has and
has not been exercised on a real machine, and macOS 14 and 15 are still on the
second list.
Belay is free and always will be. The most useful things, in order:
⭐ Star it. It costs nothing and it is how other people find this.
🐛 Report a bug. The macOS version and the agent you were running are what make a report actionable.
🌍 Fix a translation. Seven languages ship and only English and Russian have been read by a person who speaks them. One CSV per language, and it is data rather than code. This is the most wanted contribution here.
🔌 Add a preset for an agent Belay does not know yet. Also data, also no need to learn the codebase.
💛 Donate. Last on the list on purpose.
Start at CONTRIBUTING.md. Security reports go through
SECURITY.md, not the issue tracker.
| How it works | Detection, the safety rails, privacy, and talking to Belay from anything |
| FAQ | Why not caffeinate, why not CPU, why not an API key |
| Contributing | Building, testing, translating, adding a preset |
| Architecture | How the app is put together |
| Security | What Belay reads, what it cannot read, and how to verify it |
| Changelog | What changed, and why |
Belay Source-Available License 1.0. Use it anywhere, fork it, build on it. Two conditions:
🚫 You may not sell it. Not the app, not a derivative, not access to it. Use is free and stays free for everyone, including at work and for commercial work. What is forbidden is charging other people for it.
📛 Credit the original. Anything built on Belay has to say so where its users can see it: Belay by PerfectoWeb, with a link back here.
The name and the mark are separate again. TRADEMARKS.md
says exactly what that does and does not stop you doing.
Belay shows each tool's own logo in the sessions list so you can tell at a
glance which agent is working. All product names, logos and trademarks are the
property of their respective owners, used only to identify those products, and
imply no affiliation or endorsement. See NOTICE.md.
Built for people who leave their agents running and go and do something else.