macOS

How Bowline runs on macOS: the daemon LaunchAgent, the read-only Menu Bar Status App, native notification policy, accessibility, and clean uninstall.

On macOS, Bowline runs as a background daemon under a user LaunchAgent and surfaces ambient state through the Menu Bar Status App. The menu bar is read-only and trust-only: it shows workspace health and can complete a narrow device-trust approval, but the CLI and TUI stay primary for repair and any broad change. This page covers installing the app and daemon, what the menu bar shows and can't do, when native notifications fire, accessibility, and how to uninstall cleanly.

Install and the daemon LaunchAgent

The one-command installer installs Bowline.app, links the bundled bowline and bowline-daemon binaries into ~/.local/bin, registers the background daemon, and opens the Menu Bar app. On macOS, daemon registration creates a user LaunchAgent at ~/Library/LaunchAgents/io.bowline.daemon.plist that runs bowline-daemon for your account, so your workspace keeps syncing across logins without a manual start.

Install Bowline with Installation.
Confirm with bowline daemon status and bowline status.
Run bowline login to authorize the machine.

If you install with Homebrew or --cli-only, run bowline daemon install once after the binaries are on your PATH.

Manage the daemon with these commands.

Command	What it does
`bowline daemon install`	Creates `io.bowline.daemon.plist` and starts the daemon
`bowline daemon restart`	Restarts the daemon without touching sync state or project files
`bowline daemon status`	Reports the daemon's running state
`bowline daemon uninstall`	Removes the generated LaunchAgent; leaves `~/Code` intact

The Menu Bar Status App is a small status icon with a read-only dropdown. It observes the same event-backed status as bowline status, so it never invents state of its own. It's ambient by design: it reports while you work in your editor, terminal, or normal desktop flow, and it doesn't ask you to manage sync.

The dropdown surfaces these states.

What you see	Detail
Workspace health	The Workspace Status level: `healthy`, `attention`, or `limited`
Pending device approvals	Device Approval Requests, each with its short matching code
Conflicts	Sync Conflict rows, kept passive and visible, never auto-repaired
Degraded state	A Blocking Degraded State when active work can't sync, hydrate, or materialize for 60 continuous seconds
Agent activity	Active Agent Leases and followed Review-Ready Agent Leases
Limited capabilities	Any Capability Limitation, naming what still works
Handoff commands	Safe CLI commands you can copy for repair or inspection

What it can and can't do

The menu bar does three things: it observes status, completes a single narrow device-trust approval after inline confirmation, and copies safe CLI handoff commands to your clipboard. Everything else is a copy-and-run handoff to the CLI or TUI.

It is not a dashboard, control panel, or repair surface. It won't resolve a Sync Conflict, mutate the workspace, or auto-launch an agent repair, and it never steals focus. For conflict repair and broad changes, use the CLI or bowline tui.

Trust-only, read-only

The menu bar's one write action is completing a pending Device Approval Request after you confirm the matching code inline. It is not the primary approval surface: bowline status, bowline tui, and bowline approve always work the same way, including over SSH.

Native notifications

Bowline keeps the menu bar quiet. Native notifications are a convenience, never the only path to act. Every state is durable in bowline status and the dropdown first. Notifications fire only for three action-relevant states.

State	When it notifies
Device Approval Request	A signed-in device or agent host is waiting for workspace trust
Blocking Degraded State	Active work has been unable to sync, hydrate, or materialize for 60 continuous seconds
Review-Ready Agent Lease	The lease was user-started, user-followed, or already in your active review context

Bowline stays silent for normal healthy sync, hydration, indexing, conflict creation, and passive agent progress. Background automation stays passive in status.

If you miss or dismiss a notification, nothing is lost. The same item stays in bowline status and the menu bar dropdown until you act on it.

Accessibility

Bowline uses native macOS affordances throughout the menu bar app, so it works with the assistive technology you already use.

VoiceOver labels describe icon-only controls, including the status icon.
Every control in the dropdown is keyboard reachable.
Status text keeps sufficient contrast for readability.
State changes are reduced-motion-friendly.
Status indicators use more than color, so you never depend on color alone to read state.

Uninstall and recovery

Use the product path first. bowline daemon uninstall removes the generated user LaunchAgent for bowline-daemon. It does not delete project files under ~/Code.

Bowline generates these macOS artifacts.

~/Library/LaunchAgents/io.bowline.daemon.plist
~/Library/Logs entries written by macOS and the app
Bowline state and cache directories under the configured state root

If macOS reports a remaining generated artifact, remove that artifact only, then rerun the product path.

Run bowline daemon status to check the daemon's state.
Run bowline daemon uninstall again.
If the menu bar app still appears at login, remove Bowline from macOS Login Items. That affects only app startup, not the files under ~/Code.

To gather a redacted support bundle before or after uninstalling, run bowline diagnostics collect (add --json for scriptable output).

Important

Source projects are your data. Bowline's cleanup refuses any path inside an accepted project root, so removing the daemon never removes your code.

Next steps

Linux: the user systemd service and headless usage.
Status and health: the Workspace Status the menu bar mirrors.
Device trust: how Device Approval Requests work.
Agent leases: what a Review-Ready Agent Lease is.
CLI commands: full reference for bowline daemon, status, and approve.