Belay

📚 What is it?

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.

✨ Features

📦 Install

1. Download Now macOS 14 or later, Apple silicon and Intel, about 4 MB.

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.

🍺 Homebrew

brew install --cask perfectoweb/tap/belay

brew 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.

🍎 From the Mac App Store

⏳ Waiting on review. The sandboxed build exists and is what the App Store
target builds; the listing is not up yet.

🔨 Build it yourself

No Apple Developer account needed:

git clone https://github.com/PerfectoWeb/Belay.git && cd Belay
scripts/build-local.sh
open build/Belay.app

Needs 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.

🔎 Verify what you downloaded

spctl -a -vvv -t install /Applications/Belay.app
codesign -dv --verbose=2 /Applications/Belay.app

You should see source=Notarized Developer ID and team VSY2EB4Y9E.

🚀 How to Use

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.

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.

🖼 Screenshots

🧯 Troubleshooting

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.

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.

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.

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.

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.

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.

💬 Support & Contributions

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 docs/CONTRIBUTING.md. Security reports go through
docs/SECURITY.md, not the issue tracker.

📖 Documentation

📝 License

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. docs/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.