Perch

A native Mac menu bar app for sleep, sound, input controls, and an emergency stop for local AI agents.

Product site: itscool.github.io/perch.

Setup and recovery: Support guide. Dependencies: Third-party notices.

Release notes: 2.0.151 · release history · 2.0 development · 1.2 · 1.1 · 1.0. Remaining hardware acceptance is tracked in TODO.md.

Perch is a notarized Apple Silicon/macOS 26 app. Download the 2.0.151 release, or install it from the maintained Homebrew tap with brew install --cask itscool/tap/perch. Building locally still requires a local signing certificate as described below.

Keyboard controls offer independent built-in/external modifier and Fn choices, plus optional external Home/End and Page Up/Down modes. The external heading shows a connected keyboard’s name or a count; absent devices hide their controls and unknown layouts show setup guidance. Twenty-eight bundled layout profiles retain their evidence/confidence labels. Registration does not certify physical event delivery on every device. See KEYBOARDS.md.

Desk groups up to 16 computers and 16 physical monitors, with three shared presets and an editable physical layout. Play switches monitor inputs; editing saves setup. The 2.0 input session routes keyboards and mice over authenticated connections, supports pointer-edge handoff and explicitly confirmed keyboard host following, and returns control locally when readiness is lost. Input sharing starts off each run. Secure password entry requires a local keyboard. See the 2.0 implementation and QA boundary, setup/recovery, and monitor profile provenance. The protocol catalog remains available underneath Desk; the old standalone cycling workflow is retired.

Build and run

Run ./build.sh --help (or -h) for build options and signing requirements.

Builds stage the complete app and verify Sparkle's bundled runtime path, framework layout, architectures and nested signatures before replacing the output. A failed build preserves the previous app. Wait for the final Built ... message before opening the result. python3 Tools/app_bundle.py /path/to/Perch.app checks an existing bundle without launching it; python3 Tools/check-app-bundle.py tests packaging failures with disposable binaries that are compiled but never run. Help works without checking tools, downloading dependencies or building anything.

Each build reserves the next integer CFBundleVersion in Info.plist; Displayed versions use major.minor.build, such as 2.0.92. Dependency checks and preparation run before reserving a version; later compilation failures may leave gaps. Concurrent builds are refused by build/.build-lock; remove a stale lock only after confirming no build is running.

This package targets Apple silicon and macOS 26+. Building requires Xcode 26+ or matching Command Line Tools (macOS SDK 26+, Swift 6.2+) and Python 3.9+. The build checks these requirements before compiling.

Missing dependencies are prepared automatically: Sparkle 2.9.6 downloads through macOS system curl with HTTPS validation and its pinned SHA-256; corrupt downloads and edited/incomplete extracted frameworks are repaired. This avoids depending on a Python installation’s certificate bundle. The certificate library’s pinned Swift packages are fetched as needed and stale build artifacts are rebuilt. Package versions remain locked, and modified dependency source checkouts are not reset. GitHub access is needed for missing downloads; a valid Sparkle archive can be reused offline.

To prepare/check dependencies without building, changing the app version, or requiring signing credentials:

./build.sh --check-dependencies

A runnable local build needs this Mac’s own code-signing certificate/private key, default name Perch Local Code Signing, in its Keychain. It does not need the release Mac’s Developer ID identity, notarization password, or Sparkle publishing key. Use Keychain Access’s Certificate Assistant to create a local Code Signing identity if needed, then configure its local trust and confirm it appears in security find-identity -v -p codesigning. An existing local signing identity can be selected with PERCH_SIGN_IDENTITY='identity name or hash' ./build.sh. Keep the same identity for subsequent builds so access grants remain associated with that local app. The build reports missing/ambiguous identities before compilation and does not silently fall back to ad-hoc signing.

Official Developer ID signing, notarization and publication run on the release Mac through one command:

./release.sh --output build/releases/settings-fixes --publish

This prepares the release Python environment automatically and runs the resumable pipeline using the Perch Keychain profile. It requires explicit notarization and publication authorization. Use a new output folder for a new release, and the same folder to resume; omit --publish to prepare without publishing. See Release/README.md and ./release.sh --help. A local ./build.sh does not contact Apple's notarization service or install certificates automatically.

./build.sh
open build/Perch.app

To prepare a separate candidate without replacing the app in build/Perch.app, use ./build.sh --output /absolute/path/to/Perch.app. This still reserves the next build number. Building does not launch the app; launching updates outdated Perch helpers and can reapply saved input/awake choices.

Perch installs separate launchd process-monitor and input helpers on first launch. The menu app can quit while the watcher continues to run. Start at login controls the menu app; background controls and safety tracking start independently at login.

Everyday controls

• Settings → Setup & status: review setup and missing access in one place, on first use or later when something stops working. Displays, Keyboards, Scrolling, Keep awake, Agent Kill Switch, and App settings each have their own category. Ordinary changes save immediately; editors that commit related changes show Save/Cancel. Back/Close handles navigation without a redundant Done button.
• Keep awake: master switch for Perch’s idle-sleep prevention and supervised lid operation. It queries current assertions and any unowned system sleep override. Turning it off removes lid protection first (administrator authorization when needed), then releases Perch’s assertion and stops your active /usr/bin/caffeinate sessions. Cancellation stops the operation; unrelated apps’ assertions are untouched.
• Including with lid closed: available while Keep awake is on. Explicit setup installs a supervised privileged helper. A new session can start with the lid open or with the lid closed on confirmed external power. Unknown lid/power state and a closed lid on battery do not allow a new session. Closed on external power stays awake; closing on battery or undocking while closed starts 60 seconds to open the lid. If it remains closed on battery, Perch releases the override and requests sleep. Current lid operation uses a guarded system sleep override with a durable ownership journal and independent recovery. An unowned system override is not adopted or removed by Perch. Quitting Perch ends supervised lid operation. Physical sleep compatibility and hardware acceptance remain tracked in the release QA checklist.
• Turn display off: turns off the display; moving the mouse or pressing a key wakes it.
• Mute audio: queries current output mute and toggles it without changing the volume.
• Reverse trackpad scroll / Reverse mouse wheel: independently reverses only the vertical axis. Trackpad gesture/momentum phases distinguish ordinary trackpads from wheels; third-party drivers synthesizing gestures may need hardware testing.
• Swap Control ↔ Command keys: separate built-in/external controls, using macOS’s persistent per-keyboard settings. Both sides swap; defaults are unswapped.
• Use F1–F12 directly: independent controls under Built-in keyboard and External keyboards. The built-in control updates macOS while preserving connected external modes; supported external keyboards use a native per-device mode or their own firmware Fn Lock. Current modes are queried before any choice is made. See KEYBOARDS.md for support and persistence details.

Mute and modifier swaps are system settings. Fn controls use macOS or keyboard firmware; external Apple overrides need Perch running when the keyboard reconnects. Idle-awake/scroll choices are saved and reapplied by the background input helper, including after login. Quitting the menu app does not reset those choices, but it ends the supervised lid session. A restarted lid helper begins disarmed; a remembered preference alone does not re-enable it.

Scroll reversal requires Accessibility access for Perch's signed helper. External Logitech Fn control uses Input Monitoring for Perch itself; Settings → Keyboard settings provides its drag-to-Settings workflow and shows per-keyboard success or failure. Modifier swapping uses native macOS settings and needs no event tap. Settings → Input controls provides its draggable identity and verifies readiness. Certificate signing preserves the designated requirement across updates; existing input access remained granted during tested updates. The certificate is local signing, not Apple notarization or Developer ID distribution. Checkmarks indicate selected settings; the inactive remembered lid preference is explicitly labeled. Controls requiring missing access are disabled.

System display

The System panel stays at the top with muted, non-actionable labels and live readings for the chip/OS, CPU/GPU activity, memory in GiB with pressure, and macOS thermal pressure.

The Audio heading shows the current output volume while the menu is open, with a separate Muted indicator. Outputs that do not expose a volume control are labeled unavailable; no volume is changed by reading it.

Settings → Show top process and Perch CPU usage defaults on. The CPU row adds top: name percent and us: percent. Perch combines the menu app, both helpers, their completed utilities and the specific eslogger job installed for Perch. If that combined group is largest, the row shows only top: Perch percent. Collector identity uses a protected boot/PID/start-time record, not a process-name match or deprecated launchd lookup. An older collector installation needs Process event collection → Update CPU accounting… before its combined total is available; event collection itself keeps working.

All displayed CPU percentages use total logical CPU capacity, consistent with the main CPU percentage (100% means all cores). The extra readings refresh every ten seconds while the menu is open; the first interval takes two samples about one second apart, and the result appears as soon as it is ready. Native counters cover readable processes; a bounded background ps query covers protected processes without requesting additional permissions. Missing counters are marked unavailable/partial rather than zero. Top compares live user-space processes; kernel_task and processes that exit between samples are not included. Sampling stops when the menu closes or the option is off.

Agent Kill Switch

Open Perch → Settings → Agent Kill Switch.

• Panic… in the main menu asks for confirmation, then freezes and force-terminates selected local agents and their observed descendants. Unsaved agent work can be lost.
• Agents, shortcut & panic actions… selects agents, privacy-reset scope, and the configurable shortcut. The shortcut acts immediately when enabled. New configurations default to resetting privacy permissions for all apps, with Perch last; existing user selections are preserved.
• Test shortcut… waits until harmless test mode is ready, then gives ten seconds to press the combination. It reports the outcome, restores the configured shortcut, and returns to settings. No agents are stopped or permissions reset.
• Preview panic targets… shows a current preview and recent outcomes. No full command lines or environment variables are logged.
• Process event collection… verifies the optional eslogger collector, permissions and a live probe. See EVENT-COLLECTOR.md for setup and coverage limits.
• Resume agent activity… releases relaunch blocking and restores launch eligibility for jobs Perch disabled. It does not reopen apps or restore privacy grants.
• Advanced… contains recognition-catalog updates, custom agent additions, optional administrator-owned helper files, and a separate confirmed broad reset action. Repair appears when background protection needs it.

Defaults cover Codex, ChatGPT, Claude desktop, Codex CLI and Claude Code. Additional apps and specific agent executables can be selected. Generic runtimes such as node, Python and shells are deliberately not offered as custom blanket targets.

How stopping works

The watcher attributes fork/exec/exit events using full audit tokens, including PID versions, and retains descendants after their parents exit. Healthy reconciliation runs every 30 seconds, with five-second snapshots when event coverage is unavailable. Panic always drains available events and takes fresh snapshots; active lockdown checks every 250 ms. On panic it persists the blocked state, sends SIGSTOP to matches, rescans for new children, then sends SIGKILL. Birth time and ownership are rechecked immediately before signaling. It verifies exits afterward and reports failures. The watcher excludes Perch and its helpers.

While blocked, matching relaunches are repeatedly stopped. Exact matching, loaded LaunchAgent jobs are disabled/unloaded where possible, with their prior disabled state respected. Unrecognized wrappers, app login mechanisms and new launchers may still retry; polling is not a pre-execution barrier. The blocked state and live tracked identities survive watcher restarts. A boot-time marker prevents old PID records carrying across reboot.

Guardian maintenance reacts to configuration/catalog changes and request-directory notifications. A one-second revision check preserves recovery from missed notifications, in-place edits and recreated files. Unchanged inputs skip configuration processing and directory scans. Tracked-state checkpoints retain their original write timing, but sorting happens only after membership or process metadata changes. Diagnostic details are formatted only when an authenticated client reads status.

The helper is managed with launchd KeepAlive, separately from Codex and the menu process. The shortcut uses Carbon registration rather than the Accessibility event tap. Readiness shows whether the watcher is live, whether the shortcut is registered, how many processes are tracked, test mode, and errors.

Coverage limits

This is an emergency brake, not containment:

• Current-user local processes only. Root/admin agents, remote jobs, SSH jobs already detached remotely, managed services and cloud tasks are not stopped.
• Events lost before Perch starts or during collection gaps cannot be reconstructed. Snapshot fallback can miss children that detach between snapshots. Runtime wrappers outside the recognized launch patterns may need a custom target.
• Relaunched processes may execute briefly before the next sample. A same-user process can disable the launch job, modify user configuration or interfere with Perch. Administrator-owned helper files improve accidental-edit resistance but do not fix that trust boundary.
• A swallowed shortcut, stopped watcher, secure input or frozen OS can defeat software controls. Test the shortcut from the apps you use. Retain a physical shutdown fallback.
• Privacy resets use /usr/bin/tccutil; a successful exit means macOS accepted the reset, not independent proof that all ongoing access stopped. CLI permissions may belong to their terminal host. No private TCC database is edited. Admin rights, system extensions, remote sharing and every setting in Privacy & Security are not covered.
• No network isolation, remote cancellation, automatic reboot, permission restoration or rollback of prior file/network actions is attempted.

Files and removal

User jobs: ~/Library/LaunchAgents/local.scott.perch.guardian.plist and local.scott.perch.input.plist. The optional root eslogger collector is described in EVENT-COLLECTOR.md.

Configuration, tracked identities, bounded JSONL event history and helper bundle: ~/Library/Application Support/Perch/Safety/.

Live helper status stays in memory and is queried asynchronously over authenticated local XPC connections. No periodic helper status files are published. Persistent configuration, ancestry checkpoints, panic requests and the temporary shortcut-test lease retain their existing file storage.

Permission reset command logs: ~/Library/Application Support/Perch/Panic/.

Lid activity: Settings → Keep awake → Lid activity, with live updates and Copy log. The root helper and watchdog share /var/db/local.scott.perch.lid-activity/events.json, retaining at most 1,024 events from the last 24 hours. Events describe observed lid/power changes, elapsed countdowns, command outcomes and separate macOS sleep/wake notifications. History remains readable when the helper is offline; gaps in observation and command acknowledgment alone do not prove physical sleep behavior.

For removal, follow Before removing Perch. Open the lid, disable keep-awake/lid protection and confirm normal sleep is restored before removing privileged helpers or recovery jobs. If cleanup fails, retain recovery and use the support guide. Removing the app alone does not remove optional background services. Collector-specific removal is described in EVENT-COLLECTOR.md.

Verification

Fast, headless lid-policy checks:

python3 Tools/check-lid-policy.py

The first run compiles a small Swift binary; unchanged reruns reuse it. Virtual time advances instantly, including hour-long gaps. The suite compiles the actual policy, watchdog, restart and enforcement sources without AppKit, the macOS power adapter, Sparkle or signing credentials. It checks 378,504 generated transitions plus boundary/failure matrices in about one second on the development Mac. See LID-POLICY-TESTS.md for the coverage boundary.

build/Perch.app/Contents/MacOS/Perch --self-test
build/Perch.app/Contents/MacOS/Perch --settings-self-test
build/Perch.app/Contents/MacOS/Perch --safety-preview

Self-tests use synthetic ancestry and disposable local shell/sleep processes. They check descendant selection, detached history, PID reuse, exclusions, freeze/termination, preservation of unrelated processes, hotkey conflicts, reset sequencing with a mock executor, input transformations and system-state reads. No live agents are stopped and no real privacy reset is performed by tests. The preview prints only target-group counts.

bash Tools/check-release.sh verifies signing and runs both safe suites. AppKit checks exercise live menu updates during tracking, Settings navigation, light/dark rendering, input-readiness states, and shortcut-test cancellation/success/timeout/cleanup using isolated requests. They do not prove physical keyboard delivery or a real system-wide privacy reset.

See V1-NOTES.md for measured performance and validation limits, and EVENT-COLLECTOR.md for the collector architecture. REVIEW.md is an earlier implementation review. The original whole-app review is recorded in V1.2-REVIEW.md; current 2.0 work, QA, release gates and backlog are in TODO.md.

Central reset controls

Settings → Reset settings has two in-app groups: Device setup (detected monitor configuration, learned keyboard profiles, mappings and confirmations) and Perch preferences (feature choices, shortcuts and agent settings). Neither is preselected. Device reset quits Perch after forgetting setup; the next launch starts with fresh detection. Bundled profiles remain, and unknown keyboards require setup again. Preferences-only reset preserves device setup.

The same area offers explicit Perch-only privacy reset and system sleep/audio changes. System changes are not claimed as an undo of Perch-owned values: previous keyboard firmware/system values were not recorded and are left alone. All-app privacy reset is also directly available in Agent Kill Switch. It invokes tccutil without calling panic, stopping agents, or disabling launch jobs. Its scope is privacy decisions for the current account, not every permission or system setting. Perch-only reset uses its bundle identity, shared by its helpers; eslogger is a separate system tool and is not reset as part of that scope.