SYSTEM

remote mac automation

Control your Mac from anywhere using natural language. Built with Cloudflare Agents SDK for intelligent scheduling, memory, and tool orchestration.

quick start

desktop app (recommended)

The easiest way to get started. Download, install, and the app guides you through everything.

1. Download SYSTEM.dmg from releases
2. Drag to Applications
3. Launch and follow the onboarding wizard

The app lives in your menu bar and handles permissions, configuration, and auto-starts everything.

cli (advanced)

git clone https://github.com/ygwyg/system
cd system && npm install
npm run setup  # interactive wizard
npm start      # start everything

permissions

SYSTEM requires 3 macOS permissions to control your Mac. The desktop app guides you through granting these.

architecture

SYSTEM uses a split architecture for security: the Agent (brain) runs on Cloudflare Workers, while the Bridge (body) runs locally on your Mac.

┌───────────────────────────────────────────────────────┐
│                        USER                           │
│                    (phone/browser)                    │
└─────────────────────┬─────────────────────────────────┘
                      │ HTTPS
                      ▼
┌───────────────────────────────────────────────────────┐
│                  AGENT (Brain)                        │
│              Cloudflare Workers                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Claude    │  │   State     │  │  Schedules  │    │
│  │     AI      │  │  (D.O.)     │  │   (D.O.)    │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────┬─────────────────────────────────┘
                      │ Tunnel
                      ▼
┌───────────────────────────────────────────────────────┐
│                  BRIDGE (Body)                        │
│                Your Mac (local)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ AppleScript │  │    Shell    │  │   Raycast   │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└───────────────────────────────────────────────────────┘

authentication

All requests require an API secret via Bearer token or query parameter.

// Header
Authorization: Bearer <api_secret>

// Or query parameter
?token=<api_secret>

chat

Send natural language commands to control your Mac.

{
  "message": "Play some jazz music"
}

{
  "message": "Playing jazz on Apple Music",
  "actions": [{
    "tool": "music_play",
    "args": { "query": "jazz" },
    "success": true,
    "result": "Now playing: Jazz Vibes"
  }]
}

schedules

Schedule one-time or recurring tasks using natural language or cron syntax.

{
  "schedules": [{
    "id": "abc123",
    "description": "Play closing time",
    "scheduledAt": "2026-01-05T17:00:00Z",
    "cron": "0 17 * * *"
  }]
}

state

The agent maintains persistent state including preferences and conversation history.

{
  "preferences": { "wife": "Jane" },
  "historyLength": 12,
  "scheduleCount": 2
}

core tools

Foundational tools for Mac automation.

computer use agent (CUA)

Visual automation tools that let AI see and interact with any application. The CUA takes screenshots, analyzes them with Claude's vision, and executes mouse/keyboard actions.

vision & screenshots

mouse actions

keyboard actions

app & window control

utility

accessibility tools

Higher-level tools that find and interact with UI elements by role/title instead of coordinates.

computer-use endpoint

Run a full agentic loop to accomplish a visual task:

{
  "goal": "Click the Submit button",
  "maxIterations": 10,
  "app": "Safari"  // optional: focus this app first
}

{
  "success": true,
  "message": "Clicked Submit button",
  "iterations": 2,
  "actions": [
    { "tool": "cua_click", "args": {"x": 500, "y": 300}, "result": "Clicked" }
  ]
}

music

Control Apple Music playback.

system

Control system settings, get status, manage files and apps.

calendar & reminders

display & focus

system status

notes

Read and write Apple Notes.

files

Search and manage files via Finder.

shortcuts

Run Apple Shortcuts.

browser

Get info from Safari, Chrome, Arc, or other browsers.

raycast extensions

Execute Raycast extensions for powerful integrations. SYSTEM scans your installed extensions and makes them available as tools.

how it works

During npm run setup, SYSTEM scans your Raycast extensions folder and presents compatible commands for you to enable. Each enabled command becomes a dedicated tool.

Raycast Extension              SYSTEM Tool
─────────────────              ───────────
spotify-player/play      →     spotify_play
linear/create-issue      →     linear_create_issue
slack/send-message       →     slack_send_message

extension discovery

SYSTEM looks in ~/.config/raycast/extensions/ and reads each extension's package.json to find commands. Only commands with mode: "no-view" or mode: "view" are compatible.

compatible extension types

popular extensions that work well

tool naming

Tools are named as {extension}_{command} with hyphens replaced by underscores:

// Extension: linear, Command: create-issue-for-myself
Tool name: linear_create_issue_for_myself

// Extension: spotify-player, Command: play
Tool name: spotify_player_play

using raycast tools

Once enabled, just ask naturally:

• "Create a Linear issue for fixing the login bug"
• "Send a Slack message to #general saying hello"
• "Play Daft Punk on Spotify"
• "Add 'buy groceries' to my Todoist"

generic raycast tool

For extensions not in your enabled list, use the generic raycast tool:

{
  "extension": "spotify-player",
  "command": "play",
  "arguments": { "query": "jazz" }
}

deep link format

Under the hood, SYSTEM uses Raycast deep links:

raycast://extensions/{author}/{extension}/{command}?arguments={json}

troubleshooting

re-scanning extensions

If you install new Raycast extensions, run setup again to add them:

npm run setup

Your existing configuration will be preserved—you'll just see new extensions to enable.

bridge api

Direct API to the local bridge. Used by the agent, but also available for custom integrations.

{
  "tool": "open_app",
  "args": { "app": "Safari" }
}

websocket

Real-time updates for scheduled tasks and notifications.

// Connect to WebSocket
const ws = new WebSocket('wss://your-agent.workers.dev/ws?token=...');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Types: scheduled_result, notification, bridge_status
  console.log(data.type, data.payload);
};

security

SYSTEM is designed with security as a priority.

cloudflare access (recommended)

If you deploy to Cloudflare Workers, add Cloudflare Access for Zero Trust authentication at the edge — before requests even reach your agent.

setup via dashboard

1. Go to Cloudflare Zero Trust Dashboard
2. Navigate to Access → Applications → Add an application
3. Select Self-hosted and enter your worker URL
4. Create an access policy (e.g., email = you@example.com)
5. Save — users must now authenticate before accessing SYSTEM

automation (terraform)

# Note: wrangler doesn't support Access config directly
# Use Terraform for infrastructure-as-code

resource "cloudflare_access_application" "system" {
  zone_id          = var.zone_id
  name             = "SYSTEM"
  domain           = "your-agent.workers.dev"
  session_duration = "24h"
}

resource "cloudflare_access_policy" "allow_me" {
  application_id = cloudflare_access_application.system.id
  zone_id        = var.zone_id
  name           = "Allow specific emails"
  precedence     = 1
  decision       = "allow"

  include {
    email = ["you@example.com"]
  }
}