🪖 Bulchimbeon (불침번)

Your Mac's night-watch soldier.
A menu bar app that keeps your Mac awake only while your AI coding agents are actually working,
then salutes "Shift over!" and lets it sleep.

No hooks, no daemon, no installed root helper. One app. macOS 13 and later.

Bulchimbeon (불침번) is the night-watch duty in the Korean army: someone stays up all night so everyone else can sleep.
A pixel-art private takes that shift for your Mac.

🌐 한국어 · 日本語 · 简体中文

🚶 Patrol mode

The private patrols just under your menu bar with a flashlight. While standing by he looks around in the corner;
at shift change he salutes with a speech bubble. Clicks pass straight through, he fades when your pointer comes close,
and he stays out of full-screen apps (presentations, screen sharing, video). Size 2× / 3×, or turn him off.

🗣️ The private's lines

Why

To leave an agent running overnight I used to do this:

caffeinate -d                 # ...and forget to turn it off
sudo pmset disablesleep 1     # ...and forget to turn it back on → battery at 0%

Bulchimbeon stays awake only while an agent is working and hands the Mac back to normal sleep when it's done.

Features

Compared with similar apps

Adrafinil solves the same problem and came first. The two take opposite
approaches, so pick the one that fits. (As of October 2026.)

Choose Adrafinil if you're on macOS 26.4+ and want hooks to track turns precisely, or want agents to request
wake time themselves.
Choose Bulchimbeon if you're on macOS 13–15, don't want anything installed into your agent configs or system,
or would rather have a private on watch.

Install

brew install --cask s3onghyun/tap/bulchimbeon

# Update — refresh the tap first, Homebrew's auto-update interval is long
brew update && brew upgrade --cask bulchimbeon

Or download the zip from Releases and move it to /Applications.
macOS 13+, universal (Apple Silicon and Intel).

First launch: the app is ad-hoc signed and not notarized by Apple yet, so macOS blocks it once.
Try to open it, then go to System Settings → Privacy & Security → "Open Anyway".
(Since macOS 15, right-click → Open no longer bypasses this.)
Until it's notarized, macOS won't grant it notification permission, so notifications show up as "Script Editor".

Verify the download (optional)

Release zips are built only in GitHub Actions and carry a build provenance attestation.

gh attestation verify Bulchimbeon-<version>.zip --repo s3onghyun/bulchimbeon
shasum -a 256 -c Bulchimbeon-<version>.zip.sha256

How it works

Agent detection

Bulchimbeon scans your own user's processes with libproc and matches agents by executable name, argv[0],
install path or script path. Never by substring (Claude Code hooks run node -e "...'.claude'...", which would match).

Supported: Claude Code · Codex · Gemini CLI · Cursor Agent · Copilot CLI · Aider · OpenCode

Only while working. People keep several Claude Code sessions open, so counting open sessions would never let the
Mac sleep. An agent counts as working when (you can switch back to counting open sessions in the menu):

Check what gets detected on your machine, or add an agent that isn't on the list:

/Applications/Bulchimbeon.app/Contents/MacOS/Bulchimbeon --diagnose
defaults write io.github.s3onghyun.bulchimbeon customAgents -array goose amp

Agents running inside Docker or on a remote host over SSH are not processes on this Mac, so they aren't detected.

pmset -g assertions | grep Bulchimbeon   # is it on watch right now?

The duty logic lives in a pure state machine (DutyEngine) with no system calls, tested scenario by scenario with a
fake clock. Design notes, including signals we tried and rejected: docs/design.md.

Security

The app runs pmset with admin rights and reads other processes' metadata, so it has its own threat model:
SECURITY.md.

• No network access, no third-party dependencies
• No shell-injection surface: absolute paths, minimal environment, the only variable value in the admin command is an integer PID
• Never stores or prints other processes' arguments or environment; never reads AI transcripts
• Hardened runtime, SHA-256 checksums and build provenance for releases, CI actions pinned by commit SHA

Development

Only the Command Line Tools are needed, no Xcode.

make test       # unit + scenario tests
make app        # dist/Bulchimbeon.app (ad-hoc signed)
make run        # build and launch
make icons      # regenerate the app icon and preview after editing sprites

# launch and start agent watch right away
open dist/Bulchimbeon.app --args --agent-watch

# print the engine's effects to stderr (for tracing)
BULCHIMBEON_DEBUG=1 dist/Bulchimbeon.app/Contents/MacOS/Bulchimbeon

Want to help? Start with CONTRIBUTING.md.

Release (maintainer)

git tag vX.Y.Z && git push origin vX.Y.Z   # → the Release workflow builds, attests and uploads
./scripts/bump-cask.sh X.Y.Z               # → verifies checksum and provenance, then updates homebrew-tap

Sprites are ASCII grids in Sources/BulchimbeonCore/Sprites.swift: one character per pixel, drawn as vector
rectangles so both the 16 pt menu bar icon and the 1024 px app icon stay crisp.

Roadmap

Tracked as milestones. 1.0 means settings keys, command-line
flags and the duty log format stop changing: see the compatibility promise (in Korean; the
tables are self-explanatory) and the CHANGELOG.

• Pixel-art private, patrol mode, Korean/English UI
• Detect working vs. idle agents
• Homebrew cask (personal tap)
• Apple notarization and the official Homebrew cask
• Privileged helper to remove the admin prompt in lid-closed mode
• Unlockable skins: Joseon night watchman, scholar

Contributing

Bug reports ("🚨 soldier misbehaving"), agent requests, translation fixes, and ideas for lines or sprites are
all welcome. Issues and PRs in English, Korean, Japanese or Chinese are fine. Look for
good first issue to get started, and read
CONTRIBUTING.md.

Caution

Heavy, long-running work with the lid closed makes the Mac warm. Plug in power when you can.

License

MIT