/macos

name: macos
description: "Control macOS via AppleScript/osascript. Manage windows (move, resize, tile), apps (launch, quit, focus), system (volume, dark mode, notifications), Spotify, browsers, Calendar, Reminders, Finder, and clipboard. Use when the user asks to control their Mac, arrange windows, manage apps, or interact with native macOS features."
metadata:
  { "requires": { "bins": ["osascript"] } }

macOS Automation Skill

Control macOS apps, windows, and system features via `osascript` through the Bash tool. All commands run AppleScript one-liners.

**Permissions:** Window management and UI scripting require Accessibility permission for Terminal/iTerm2 (System Settings > Privacy & Security > Accessibility). App control, volume, notifications, Spotify, browsers, Calendar, Reminders, and Finder work without it.

---

Window Management

> Requires Accessibility permission

Get screen size

osascript -e 'tell application "Finder" to get bounds of window of desktop'
# Returns: 0, 0, 1920, 1080 (x1, y1, x2, y2)

Get window bounds

# Frontmost app's front window
osascript -e 'tell application "System Events" to tell (first process whose frontmost is true) to get {position, size} of window 1'

# Specific app
osascript -e 'tell application "Safari" to get bounds of front window'

Move / resize

# Set bounds: {x1, y1, x2, y2}
osascript -e 'tell application "Safari" to set bounds of front window to {0, 25, 960, 1080}'

# Using System Events (works for any app)
osascript -e 'tell application "System Events" to tell process "Safari" to set position of window 1 to {100, 100}'
osascript -e 'tell application "System Events" to tell process "Safari" to set size of window 1 to {800, 600}'

Tile left / right half

# Left half (1920x1080 screen, 25px menu bar)
osascript -e 'tell application "Safari" to set bounds of front window to {0, 25, 960, 1080}'

# Right half
osascript -e 'tell application "Google Chrome" to set bounds of front window to {960, 25, 1920, 1080}'

Dynamic tiling (auto-detect screen size)

osascript -e '
tell application "Finder" to set screenBounds to bounds of window of desktop
set W to item 3 of screenBounds
set H to item 4 of screenBounds
tell application "Safari" to set bounds of front window to {0, 25, W / 2, H}
tell application "Google Chrome" to set bounds of front window to {W / 2, 25, W, H}
'

Minimize / restore

osascript -e 'tell application "Safari" to set miniaturized of window 1 to true'
osascript -e 'tell application "Safari" to set miniaturized of window 1 to false'

List all windows

osascript -e 'tell application "System Events" to get {name, position, size} of every window of every process whose visible is true'

Focus a window by title

osascript -e 'tell application "Safari" to activate' -e 'tell application "Safari" to set index of window "Page Title" to 1'

---

App Management

Launch / activate (bring to front)

osascript -e 'tell application "Safari" to activate'

Quit

osascript -e 'tell application "Safari" to quit'

# Only if running
osascript -e 'tell application "Safari" to if it is running then quit'

Hide

osascript -e 'tell application "System Events" to set visible of process "Safari" to false'

List running GUI apps

osascript -e 'tell application "System Events" to get name of every process whose background only is false'

Check if app is running

osascript -e 'application "Safari" is running'
# Returns: true / false

Get frontmost app

osascript -e 'tell application "System Events" to get name of first process whose frontmost is true'

---

System Controls

Volume

# Get volume (0-100)
osascript -e 'output volume of (get volume settings)'

# Set volume
osascript -e 'set volume output volume 50'

# Mute / unmute
osascript -e 'set volume output muted true'
osascript -e 'set volume output muted false'

# Check mute status
osascript -e 'output muted of (get volume settings)'

Dark mode

# Get status
osascript -e 'tell application "System Events" to tell appearance preferences to get dark mode'

# Toggle
osascript -e 'tell application "System Events" to tell appearance preferences to set dark mode to not dark mode'

# Set explicitly
osascript -e 'tell application "System Events" to tell appearance preferences to set dark mode to true'

Notifications

# Simple
osascript -e 'display notification "Done!" with title "Agent" sound name "Glass"'

# With subtitle
osascript -e 'display notification "Build succeeded" with title "CI" subtitle "main branch" sound name "Purr"'

Dialog / alert (blocks until dismissed)

# Alert
osascript -e 'display alert "Heads up" message "Deployment starting in 5 minutes"'

# Input dialog
osascript -e 'display dialog "Enter name:" default answer ""'
# Returns: button returned:OK, text returned:...

---

Spotify

> Spotify must be running. These do NOT require Accessibility permission.

# Play / pause / next / prev
osascript -e 'tell application "Spotify" to playpause'
osascript -e 'tell application "Spotify" to next track'
osascript -e 'tell application "Spotify" to previous track'

# Current track info
osascript -e 'tell application "Spotify" to get {name of current track, artist of current track, album of current track}'

# Player state: playing / paused / stopped
osascript -e 'tell application "Spotify" to player state'

# Volume (0-100)
osascript -e 'tell application "Spotify" to sound volume'
osascript -e 'tell application "Spotify" to set sound volume to 60'

# Shuffle / repeat toggle
osascript -e 'tell application "Spotify" to set shuffling to not shuffling'
osascript -e 'tell application "Spotify" to set repeating to not repeating'

# Seek to position (seconds)
osascript -e 'tell application "Spotify" to se