# macOS (/docs/platforms/macos)



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 [#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.

1. Install Bowline with [Installation](/docs/getting-started/installation).
2. Confirm with `bowline daemon status` and `bowline status`.
3. 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 [#the-menu-bar-status-app]

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 [#what-it-can-and-cant-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`.

<Callout type="warn" title="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.
</Callout>

## Native notifications [#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.

<Callout type="info">
  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.
</Callout>

## Accessibility [#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 [#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.

1. Run `bowline daemon status` to check the daemon's state.
2. Run `bowline daemon uninstall` again.
3. 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).

<Callout type="warn" title="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.
</Callout>

## Next steps [#next-steps]

* [Linux](/docs/platforms/linux): the user systemd service and headless usage.
* [Status and health](/docs/concepts/status-and-health): the Workspace Status
  the menu bar mirrors.
* [Device trust](/docs/concepts/device-trust): how Device Approval Requests
  work.
* [Agent leases](/docs/concepts/agent-leases): what a Review-Ready Agent Lease
  is.
* [CLI commands](/docs/cli/commands): full reference for `bowline daemon`,
  `status`, and `approve`.