refresh-computer-tools

macOS computer automation via Swift CoreGraphics. Screenshot, click, type, key press, scroll, drag, hover, zoom — all from the command line or as a library.

No Python, no pyobjc, no third-party dependencies. Uses Swift and screencapture, which are built into every Mac.

Install

npm install -g refresh-computer-tools

Or run directly:

npx refresh-computer-tools screenshot

CLI

# Screenshot (captures all displays, returns JPEG base64)
refresh-computer-tools screenshot

# Click at model coordinates (max 1280px on longest axis)
refresh-computer-tools click 640 416
refresh-computer-tools click 640 416 --button right

# Double-click
refresh-computer-tools double-click 640 416

# Type text (uses pbcopy + Cmd+V)
refresh-computer-tools type "Hello world"

# Key press with optional modifiers
refresh-computer-tools key-press return
refresh-computer-tools key-press space --modifiers command
refresh-computer-tools key-press a --modifiers command,shift

# Scroll
refresh-computer-tools scroll --dx 0 --dy -3

# Mouse move
refresh-computer-tools mouse-move 640 416

# Hover (move + wait)
refresh-computer-tools hover 640 416 --duration 600

# Drag
refresh-computer-tools drag 100 100 500 500
refresh-computer-tools drag 100 100 500 500 --button right --duration 400

# Zoom (crop a region from a screenshot)
refresh-computer-tools zoom 200 200 600 600

# Screen size (model coordinate space)
refresh-computer-tools screen-size

# Display info
refresh-computer-tools displays

All coordinates are in model space (the longest screen axis is scaled to 1280px). Output is JSON.

Library

import { click, keyPress, typeText, captureScreenshot, getScreenSize } from 'refresh-computer-tools';

const screenshot = captureScreenshot();
// { image: 'base64...', format: 'jpeg', imagePath: '/tmp/...', thumbnailPath: '/tmp/...' }

const result = click(640, 416);
// { clicked: true, x: 756, y: 492, image: '...', ... }

const size = getScreenSize();
// { width: 1280, height: 831 }

How it works

• Screenshots: screencapture -x (captures all displays into one image)
• Input actions: Swift CoreGraphics via swift - (CGEvent API for mouse, keyboard, scroll)
• Image processing: sips (resize, format conversion, thumbnails)
• Display detection: Swift AppKit NSScreen.screens
• Coordinate mapping: Model space (max 1280px) mapped to logical screen coordinates

Requirements

• macOS
• Node.js 18+
• Accessibility permission for the terminal app (System Settings > Privacy & Security > Accessibility)

License

MIT