MacBridge is a TypeScript-friendly native macOS automation adapter.
It provides a Swift native runtime plus a TypeScript package for agent systems that need to inspect displays, windows, permissions, screenshots, accessibility state, typed actions, observations, and evidence artifacts.
MacBridge is public-alpha software. It already does useful native work, but the higher-level SDK shape is still evolving before the first stable release.
npx macbridge
npx macbridge --help
npx macbridge permissions check
npx macbridge displays listMacBridge currently targets Apple Silicon Macs only. Running npx macbridge
uses the packaged signed .pkg installer, then opens
/Applications/MacBridge.app so macOS permission prompts attach to the stable
app identity.
bun add macbridgeDouble-clicking the installed app opens the MacBridge shell and permission
surface. After installation, developer workflows can use the macbridge
command.
npx macbridge windows list
npx macbridge capture display main --png -o screenshot.pngTypeScript usage:
import { createControlPlane, runJSON, type Json } from "macbridge";
const displays = runJSON<Json>(["displays", "list"]);
const mac = createControlPlane();
const permissions = mac.permissions({ require: false });Source-owned TypeScript commands:
macbridge observe window <wid> --display-screenshot main --ax --out tmp/observations/window
macbridge act action.json
macbridge verify expectation.json
macbridge agent models --type text --provider openai --json
macbridge prefs init --preferred-screen left
macbridge apps list
macbridge apps observe helium --launch
macbridge terminal start --screen left --session macbridge
macbridge terminal send "echo hello" --session macbridgeWorkspace preferences live at ~/MacBridge/preferences.toml. App-specific
behavior lives behind src/apps adapters, and the terminal lane uses a selected
terminal adapter backed by tmux so MacBridge can drive a dedicated screen while
the human keeps working elsewhere.
Architecture and contract decisions live under docs/development/rfcs.
Current RFC index:
Active RFCs:
- RFC-0007: App Identity and Icon Distribution
- RFC-0008: Model Agnostic Agent Loop
- RFC-0010: Multimodal Evidence and Session Video
- RFC-0011: Inviting CLI and Shell Experience
The current public TypeScript surface includes:
- native command helpers:
run,runJSON - binary path helpers:
defaultBin,packagedBin,resolveDefaultBin MacBridgeand theControlPlaneprotocol- typed observation, action, verification, planning, and recording helpers
- package CLI semantics for
agent,observe,act, andverify - media probing and recording helpers
MacBridge is useful today for deterministic macOS automation and local agent experiments. The next major product work is to make the TypeScript API more domain-shaped, with stable operations for displays, windows, capture, observation, permissions, and actions.
MIT