# Mac Use

Mac Use is agent-neutral computer use for macOS. It gives any MCP-capable
agent:

- an accessibility-first managed browser;
- a visible cursor that moves to each browser action;
- an active-tab favicon badge;
- a native menu-bar indicator for apps currently in use;
- a user-facing **Stop Using** action; and
- browser screenshots returned as standard MCP image content.

It does not choose or host an LLM. Agents keep their existing model,
subscription, memory, tools, and approval system.

## Install

```sh
curl -fsSL https://raw.githubusercontent.com/CarlvinceTan/mac-use/main/install.sh | bash
```

The installer is user-local and does not use `sudo`. It downloads the source,
uses an existing Node.js 24 runtime or installs a private verified copy, builds
the native menu app, installs a managed browser, and prints the MCP
configuration to add to the agent.

Requirements:

- macOS 13 or newer; and
- Xcode Command Line Tools.

If the command-line tools are missing, install them once with:

```sh
xcode-select --install
```

## Connect an agent

Print the MCP configuration at any time:

```sh
"$HOME/Library/Application Support/Mac Use/bin/mac-use" mcp-config
```

Set `MAC_USE_AGENT_ID` and `MAC_USE_AGENT_NAME` differently for each connected
agent. Agents without MCP can implement the small authenticated loopback
protocol in [docs/adapter-protocol.md](docs/adapter-protocol.md).

## Computer-use tools

- `mac_begin_activity`, `mac_update_activity`, `mac_end_activity`
- `mac_activity_snapshot`, `mac_check_stop`
- `browser_open`, `browser_snapshot`
- `browser_click`, `browser_hover`, `browser_type`, `browser_fill`
- `browser_press`, `browser_screenshot`, `browser_end`

Browser snapshots expose accessibility references such as `@e1`. Before a
targeted action, Mac Use resolves the element bounds, animates the visible
cursor to the target, waits for the extension to acknowledge its arrival, and
then performs the action. The user's physical pointer is never moved.

## Manage the installation

Check it:

```sh
"$HOME/Library/Application Support/Mac Use/bin/mac-use" doctor
```

Remove it:

```sh
"$HOME/Library/Application Support/Mac Use/bin/mac-use" uninstall
```

The default uninstall moves Mac Use to Trash. Add `--purge` for permanent
removal.

## Security

- Services bind only to `127.0.0.1`.
- Mutations require a random local bearer token.
- Browser data stays in a dedicated local profile.
- No model credentials are read or stored.
- The one-line installer downloads only over HTTPS. Pin a release with
  `MAC_USE_REF` when reproducibility matters.

See [SECURITY.md](SECURITY.md) for the trust boundary.

## Scope

Version 0.1 controls the managed browser and exposes activity indicators for
native app controllers. It does not yet click or type in arbitrary macOS apps;
an agent needs its own accessibility controller for non-browser applications.

The artwork is original and has no runtime dependency on another agent app.
Rendering can vary with macOS versions.

## Development

```sh
npm install
npm test
npm run test:swift
npm run build:mac
```

Local app builds are ad-hoc signed. Public binary releases require Developer ID
signing and notarization; see [docs/distribution.md](docs/distribution.md).

Mac Use is MIT licensed.