# Herdr Computer Use

A macOS helper and MCP server for observing and operating desktop apps, including existing browser windows and signed-in sessions. The Herdr plugin supplies explicit management actions; the helper runs independently of Herdr and its plugin checkout.

Requires macOS 14+, Node 22+, Swift 6 / Xcode command-line tools, and Herdr 0.7.0+ for plugin use. Builds target the current Mac's architecture. There is no browser extension or DOM access.

```sh
npm ci
npm run check
herdr plugin link "$PWD"
```

`check` typechecks, runs Node/native and external socket tests, builds the signed app, verifies its signature, and validates the manifest with Herdr's real parser in temporary configuration roots. It does not install the helper, launch a desktop app, register a real plugin, invoke setup, or change agent settings. Herdr must be on PATH. Managed sandboxes that deny AF_UNIX bind show explicit test skips; normal-host socket acceptance remains required. See [manual verification](docs/manual-verification.md).

To install and start the helper intentionally, follow [setup and MCP configuration](docs/setup.md). Setup opens a permission window; you grant Accessibility and Screen Recording in macOS settings. Installation and plugin linking do not configure any agent's MCP connection.

## Agent skill

This repository includes the portable [computer-usage-macos skill](skills/computer-usage-macos/SKILL.md). It guides an agent through readiness checks, accessibility-first observation, snapshot-scoped actions, and verifying results—including leaving drafts unsent when requested. The skill requires the MCP server to be configured separately using the instructions above. `herdr plugin link` registers the plugin but does not install the skill into an agent runtime; install the skill separately with the skill manager supported by that agent. Once this repository is available from GitHub, users of the Skills CLI can install it with `npx skills add <owner>/<repo> --skill computer-usage-macos`.

Default signing is ad-hoc. For a stable signing identity, set `HERDR_COMPUTER_USE_SIGN_IDENTITY` when building; permission persistence must be checked on the installed helper. This is a local desktop service, with no TCP listener, SSH forwarding, remote desktop, Linux or Windows provider.

Reused Orca code is MIT licensed, copyright 2026 Lovecast Inc. See [LICENSE](LICENSE) and [source provenance](THIRD_PARTY_NOTICES.md).