You start a long Claude Code or Codex task and walk away. Ten minutes later your Mac sleeps, the run stops making progress, and you come back to unfinished work.
Belay is a macOS menu bar app that fixes exactly that. It watches your local coding agents, keeps the Mac awake while work is still happening, and lets it sleep normally again when the work is done.
No timer to start. No sleep setting to remember to change back.
| 🎯 Zero setup | Claude Code and Codex are detected automatically. Nothing to configure, no key to paste. |
| 🔌 More agents | Gemini CLI, Copilot CLI, OpenCode, Cline, Aider and Pi ship as presets. For anything else, watch a folder or process, or connect it yourself in the direct build. |
| 🛡 Lets go | Normal holds expire after 120 seconds unless Belay renews them. If Belay disappears, the Mac goes back to normal by itself. |
| 🔋 Safety limits | Set a maximum awake time and a battery floor. Belay also lets go on sleep, quit and mode changes. |
| 👀 Subagents too | Parallel subagents count as part of the session they belong to, not as noise. |
| 📊 Time saved | Belay counts the time it kept your Mac awake while you were away, when sleep could actually have interrupted the work. |
| 🔒 Stays local | Agent detection stays on your Mac. No account, analytics or telemetry. Direct builds can check GitHub once a day for updates; you can turn that 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.
Belay - Awake for AI Agents, free, macOS 14 or later. The sandboxed build, so it updates through the store rather than through Sparkle and has no network access at all.
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) | Keeps your Mac awake while an agent is working |
| ☀️ Always On | Keeps it awake until you turn it off |
| 🌙 Off | Belay stays out of the way |
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
Out of the box, no: 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.
Since 1.3 the direct build can, as an opt-in. Keep working with the lid closed in Settings installs a system helper – macOS asks for your approval – that holds the OS's own sleep switch while an agent is working, and always lets go by itself: when the work ends, when Belay stops asking for it, after a hard time cap, or the moment the Mac runs hot with the lid shut. Proven on battery with no display attached, and the control run without it slept in seventy seconds.
The App Store build cannot install a privileged helper (that is Apple's rule, and a good one), so it does not offer the switch.
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 – and since 1.3, one to dim it to a glow at night while it is kept awake, so a screen held for an overnight run does not light an empty room. It brightens back the moment you return.
Belay does not see my agent
Claude Code and Codex need no setup. Everything else is configured in Settings ▸ Providers: switch on a preset – Gemini CLI, Copilot CLI, OpenCode, Aider, Cline and Pi ship ready-made – or point Belay at a folder or process your tool uses while it works.
In the direct build, tools that can run a shell command can also talk to Belay
directly. See
docs/HOW-IT-WORKS.md.
It says "needs setup"
Since 1.3.2 the badge says which case you are in: a folder that does not exist yet simply has not been created by the tool (it appears after the first run), and only a folder that exists but cannot be read is an access question. Presets are configuration, not code, so open Settings ▸ Providers and correct the path if yours lives elsewhere. 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; macOS 14, 15 and 26 have all been
run for real.
Belay is free and always will be. The most useful things, in order:
⭐ Star it. It costs nothing and helps other people find it.
🐛 Report a bug. The macOS version and the agent you were running are what make a report actionable.
🌍 Fix a translation. Belay is multilingual, 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 docs/CONTRIBUTING.md. Security reports go through
docs/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 |
| Roadmap | Where Belay is going, and what has to be true first |
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 covered separately.
docs/TRADEMARKS.md explains 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.