Documentation
How Macotron works, what it can do, and every macotron.* call a plugin can make.
Guide
- Getting started
- Install Macotron, pick a workdir, add plugins from the catalog, and grant permissions.
- Writing plugins
- The shape of a plugin file, how it loads and reloads, and how to log, handle errors, and save state.
- Plugin settings
- Declare a plugin's title, permissions, and options so users can configure it in Settings → Plugins.
- Coding agents
- Use Claude Code, Codex, or another agent to write plugins. Macotron writes the AGENTS.md they read.
- Permissions
- Each macOS permission Macotron can ask for, what needs it, and how to grant it.
- Security
- How Macotron decides which plugin code may run, and what an enabled plugin can do.
- Community plugins
- Install plugins other people publish on GitHub, and publish your own with one repository topic.
- Updates
- How Macotron updates itself, how to change how often it checks, and how built-in plugins update.
- Troubleshooting
- Read Macotron's log, and fix plugins that do not load, hotkeys that do not fire, and missing menu bar items.
Features
- Launcher
- Open apps, run plugin commands, and search files from one keyboard-driven bar.
- Hotkeys
- Global keyboard shortcuts from plugins, apps, and launcher rows, all changeable in Settings.
- Window management
- Tile windows with hotkeys, snap them by dragging, place them on a grid, and save layouts.
- File search
- Find files and folders by name in the launcher, from an index Macotron keeps in memory.
- Clipboard
- Search recent copies from the launcher, bring back images, and paste as plain text.
- Snippets
- Type a short abbreviation anywhere and Macotron replaces it with longer text.
- Menu bar
- The Macotron menu, its warning dots, and the status items that plugins put in the menu bar.
- Meetings and calendar
- Your next meeting in the menu bar, a join overlay when it starts, a mini calendar, and reminders.
- Screen tools
- Copy text or a QR code off the screen, pick colors, and tint, dim, or brighten the display.
- AI
- Chat with Apple Intelligence, Claude, or Gemini, translate selected text, and where API keys go.
- Browser picker
- Open each link in the right browser, by host, or pick one from a panel every time.
- Fan control
- See fan speed in the menu bar and keep the fans at or above 50% or 100% with the background helper.
- Built-in plugins
- Every plugin that ships with Macotron, with one line on what it does and what it needs.
API
- Globals
- console, timers, localStorage, and dialogs, plus what a browser or Node has that Macotron does not.
- macotron (core)
- Plugin metadata, launcher commands, host events, timers, dialogs, and logging.
- macotron.ai
- Send prompts to Claude, OpenAI, Gemini, or the on-device Apple Intelligence model.
- macotron.app
- List, find, launch, switch to, hide, and quit apps, and pick items from their menus.
- macotron.appletv
- Find Apple TVs on the local network, pair with the PIN they show, and send remote keys.
- macotron.audio
- List audio devices, switch input and output, set volume and mute, and record the microphone.
- macotron.ax
- Read the selected text, walk another app's UI elements, press buttons, and set field values.
- macotron.bonjour
- Find Bonjour services such as AirPlay receivers, printers, and other Macs on the local network.
- macotron.calendar
- Read upcoming Calendar events, with the meeting join link pulled out for you.
- macotron.camera
- List cameras, show a live preview window, and take a PNG snapshot from it.
- macotron.clipboard
- Read and write the pasteboard, keep a short history, and force plain-text paste.
- macotron.contacts
- List and search the people in Contacts, with their emails and phone numbers.
- macotron.disks
- List mounted volumes with their size and free space, and eject a disk.
- macotron.display
- List displays, set brightness and gamma, and switch Night Shift, True Tone, grayscale, XDR, and CRT.
- macotron.dock
- Read the badges on Dock icons, such as unread counts in Mail or Messages.
- macotron.event
- Post synthetic clicks, keys, text, and scrolls, and watch or swallow input from every app.
- macotron.files
- Search file and folder names in Macotron's own fast index of the folders you choose.
- macotron.fs
- Read, write, list, rename, open, reveal, trash, and watch files anywhere your user account can reach.
- macotron.hid
- List HID devices, open one, and send and read raw input, output, and feature reports.
- macotron.homekit
- Run Home scenes and accessory actions, kept as shortcuts in one Shortcuts folder.
- macotron.http
- Make GET, POST, PUT, and DELETE requests and read the status, body, and headers.
- macotron.idle
- Read how long the user has been away, and get events when the Mac goes idle and comes back.
- macotron.image
- Convert images between JPEG, PNG, HEIC, and TIFF, with quality and size limits.
- macotron.keyboard
- Global hotkeys the user can rebind, the current modifier keys, and a Hyper key.
- macotron.keychain
- Store API keys, tokens, and other secrets in the macOS Keychain.
- macotron.launcher
- Add rows to the Macotron launcher, from a fixed list or computed from what the user types.
- macotron.media
- Read what is playing in any app and send play, pause, next, and previous.
- macotron.menubar
- Put status items in the menu bar, give them menus, and add rows to the Macotron menu.
- macotron.mouse
- Read where the pointer is and which buttons are down, and move the pointer.
- macotron.network
- Read and switch Wi-Fi, Bluetooth, and AirDrop, list interfaces and byte counters, and ping a host.
- macotron.notes
- List the notes in Apple Notes and open one.
- macotron.notify
- Post system notification banners and show short on-screen toasts.
- macotron.ocr
- Read the text in an image file or a base64 PNG with Apple's on-device Vision OCR.
- macotron.panel
- Open floating web-view windows and exchange messages with the page inside them.
- macotron.player
- Play internet radio and podcasts with Macotron's own audio player.
- macotron.plist
- Read property list files and parse plist text or bytes into plain JavaScript values.
- macotron.power
- Keep the Mac awake, lock, sleep, log out, restart, or shut down, and react to sleep and lock.
- macotron.prefs
- Read and write your user's preference domains, the same values defaults reads and writes.
- macotron.qr
- Read QR codes from images, the screen, or the camera, and make QR code images.
- macotron.reminders
- List, add, and complete reminders in the Reminders app.
- macotron.screen
- Capture the screen or a dragged region as a PNG, and pick a color with the system eyedropper.
- macotron.share
- Open the macOS share menu for files, text or a link, or send files with AirDrop.
- macotron.shell
- Run a command-line tool and get back its output and exit code.
- macotron.shortcuts
- List your Shortcuts and run one by name.
- macotron.snippets
- Keep text snippets under short abbreviations that expand as you type in any app.
- macotron.spaces
- List desktops on every display, switch to one, and move a window to another desktop.
- macotron.speech
- Speak text aloud with a system voice.
- macotron.spotlight
- Find files and folders by name with Spotlight, and complete typed paths one folder at a time.
- macotron.system
- CPU, GPU, memory, disk, processes, battery, fans, appearance, Focus, locale, and time zones.
- macotron.udp
- Send UDP datagrams and listen on a port for incoming messages.
- macotron.url
- Route links to plugin handlers, open URLs in a chosen app, and act as the default browser.
- macotron.usb
- List attached USB devices and react when one is plugged in or removed.
- macotron.window
- List, focus, move, tile, and snap the windows of every app, and restore saved layouts.