Mac-A-Tron Logo Mac-A-Tron

Powerful macOS Automation for Stream Deck

Version 0.1.1

Table of Contents

Introduction

Mac-A-Tron started as a way to solve a frustrating problem: BetterTouchTool's Stream Deck integration wasn't working on my corporate system, likely due to security software like CrowdStrike/FalconStrike interfering with the closed-source BTT plugin.

Rather than just patch the problem, I built a better solution—one that could handle more types of triggers and let you choose them from a dropdown menu instead of typing UUIDs. The BTT integration worked beautifully, and life was good.

But then I realized: if I could send commands to one app, why not extend it further? That's when Mac-A-Tron evolved into a comprehensive toolkit:

All of this is powered by robo, a native Swift helper binary that provides reliable macOS automation where JavaScript alone falls short. It handles accessibility permissions properly, works with security software, and gives you the low-level control needed for real productivity tools.

💡 Philosophy: This plugin prioritizes reliability and power-user features over simplicity. If you want quick keyboard shortcuts, macOS and Stream Deck already do that. But if you want to manipulate clipboard contents mid-workflow, cycle windows across monitors with state memory, or toggle browsers based on context—this is your tool.

Installation & Setup

⚠️ Accessibility Permission Required

This plugin requires macOS Accessibility permissions to function. When you first use any action, you'll be prompted to grant permission.

  1. Download and install the Mac-A-Tron plugin from the Stream Deck store
  2. When prompted, grant Accessibility permissions:
    • Open System Settings → Privacy & Security → Accessibility
    • Click the lock icon to make changes
    • Add the robo helper binary and enable it
  3. Add actions to your Stream Deck from the plugin category

Available Actions

Keyboard Shortcut Icon
⌨️ Keyboard Shortcut

Type text and keyboard shortcuts with powerful clipboard manipulation capabilities.

Configuration

Keyboard Shortcut Configuration
  • Shortcut String: The text and commands to execute using the modern {curly brace} syntax

Basic Usage

Hello World{enter}

Plain text is typed as-is. Special keys use {curly braces}.

Clipboard Manipulation

The Keyboard Shortcut action includes a powerful clipboard buffer system:

Command Description
{grab} Copy clipboard to Robo buffer
{put} Paste Robo buffer to clipboard
{paste} Type the Robo buffer contents
{insert before <text>} Add text to start of buffer
{insert after <text>} Add text to end of buffer
{trim before <text>} Trim everything before and including text
{trim after <text>} Trim everything after and including text

Advanced Example: Archive.is URL

Create an archive.is link from the current URL in a web browser tab:

{cmd+l}{cmd+a}{cmd+c}{grab}{insert before http://archive.is/}{trim after ?}{put}{cmd+v}

This:

  1. Copies selected text ({cmd+c})
  2. Grabs it to the buffer ({grab})
  3. Removes everything after the ? ({trim after ?})
  4. Prepends http://archive.is/ ({insert before ...})
  5. Types the result ({paste})
💡 Note: This action uses the modern robo keys command with full {curly brace} syntax for all operations, including modifiers and special keys.
Browser Tab Icon
🌐 Browser Tab

Switch to an existing browser tab or create a new one if not found.

Configuration

Browser Tab Configuration
  • Browser: Select from available browsers (Chrome, Safari, Orion, etc.)
  • Target: Choose from predefined targets or create custom ones

Predefined Targets

  • Gmail: mail.google.com
  • Google Calendar: calendar.google.com

Custom Targets

You can create custom targets with:

  • Name: Display name for the target
  • URL Pattern: Part of the URL to match (e.g., github.com)
  • Title Pattern: Part of the tab title to match (use || for multiple patterns)
  • URL: Full URL to open if tab not found
💡 Tip: Title patterns support multiple matches using ||. For example: " - Gmail||Gmail: Private"
💡 Use Case: With the ability to copy and manipulate the clipboard, and to include delays, I use this to automate some web tasks including modifying a URL to use an archive service, then opening that URL in a new tab if not already open.
Browser Default Icon
🔄 Browser Default

Toggle between two default browsers or select from available browsers.

Configuration

Browser Default Configuration
  • Browser A & B: Select two browsers to toggle between
  • Clicking the button toggles the macOS default browser
  • The button shows the currently active browser
💡 Use Case: Quickly switch between personal and work browsers, or between different browser profiles.
In my case, I use Orion as a privacy-and-speed oriented browser, but have it bolted down tightly enough that some sites don't work properly. When I need to open such a site, especially from an app such as Quicken or an email client, quickly switching to Safari solves it.
Move Mouse Icon
🖱️ Move Mouse

Move mouse cursor to window center or screen.

Configuration

Move Mouse Configuration
  • Target: App (active window) or Screen
  • Screen Number: Which screen to move to (0 = primary)
  • Position: Center or Home (upper-left)
Move App Icon
🪟 Move App

Move and resize the focused window with smart positioning and multi-monitor support. A minimal window manager.

Configuration

Move App Configuration

Configure three types of button presses:

  • Single Tap: Default action (e.g., move right)
  • Long Press: Alternative action (e.g., maximize height)
  • Double Tap: Third action (e.g., move left)

Window States

Horizontal (Left/Right):

  1. Original Position: Proportionate size, centered
  2. Full Width: Spanning entire screen width
  3. Align Right: Proportionate width, aligned to right edge
  4. Align Left: Proportionate width, aligned to left edge

Vertical (Up/Down):

  1. Full Height: Same width, maximum height
  2. Almost Full Screen: Full screen with small margin
  3. Original Size: Return to initial dimensions

Down (Special):

  1. Window Visible
  2. Window Minimized

Multi-Monitor Support

When a window is aligned to the edge (state 2 or 3):

  • Pressing Right from Align Right moves to next monitor as Align Left
  • Pressing Left from Align Left moves to previous monitor as Align Right
💡 Smart Memory: The plugin remembers each app's original size and position independently.
BTT Trigger Icon
🔧 BetterTouchTool Trigger

Execute BetterTouchTool triggers directly from Stream Deck.

Configuration

BTT Trigger Configuration
  • Trigger Type: Named Trigger (643) or Stream Deck Widget (719)
  • Trigger: Select from available triggers fetched from BTT
⚠️ Requires BetterTouchTool

BetterTouchTool must be running and the webserver must be enabled in BTT preferences.

Time Zone Clock Icon
🌍 Time Zone Clock

Display time in multiple time zones with custom labels. Cycle through up to 5 different time zones.

Configuration

Time Zone Clock Configuration
  • Time Zones (1-5): Select from world time zones
  • Custom Labels: Give each time zone a friendly name (e.g., "Home", "Office", "London")
  • 24-Hour Format: Toggle between 12-hour and 24-hour display
  • Click to Cycle: Press the button to rotate through configured time zones
💡 Use Case: Perfect for remote teams, international business, or tracking time in different locations. The button displays the current time zone's label and automatically updates every 15 seconds.
Countdown Timer Icon
⏱️ Countdown Timer

Set a countdown timer with custom duration and title. Visual countdown display with alert on completion.

Configuration

Countdown Timer Configuration
  • Title: Custom label for the timer (e.g., "Meeting", "Break Time")
  • Duration: Set time in format MM:SS or HH:MM:SS
  • Start/Stop: Press button to start countdown
  • Reset: Long press to reset timer

Examples

  • 5:00 - 5 minute timer
  • 25:00 - 25 minute Pomodoro
  • 1:30:00 - 1 hour 30 minute timer
💡 Tip: Great for Pomodoro technique, meeting reminders, or timed breaks. The display counts down in real-time and alerts when complete.
Stopwatch Icon
⏲️ Stopwatch

Simple stopwatch to track elapsed time with start, stop, and reset functionality.

Configuration

Stopwatch Configuration
  • Start: Press button to begin timing
  • Stop: Press again to pause
  • Resume: Press while paused to continue
  • Reset: Long press to reset to zero
💡 Use Case: Track time spent on tasks, measure presentation length, or time any activity. Display shows elapsed time in HH:MM:SS format.

Key Reference

All keys that can be used inside {curly braces}:

Modifiers

  • cmd, command
  • ctrl, control
  • alt, option
  • shift

Letters & Numbers

  • Letters: a-z
  • Numbers: 0-9

Function Keys

  • f1 through f20

Special Keys

  • enter, return
  • tab, space
  • escape, esc
  • delete, backspace
  • left, right, up, down
  • home, end
  • pageup, pagedown

Punctuation

  • minus, equal
  • leftbracket, rightbracket
  • semicolon, quote
  • backslash, comma
  • slash, period
  • grave (backtick)

Literal Characters

For typing special characters:

  • leftbrace → {
  • rightbrace → }
  • doublequote → "
  • colon → :
  • question → ?

Media Keys

  • volumeup
  • volumedown
  • mute

Commands

  • {pause N} - Pause for N milliseconds

Modifier Combinations

{cmd+c}           - Command+C
{ctrl+alt+delete} - Ctrl+Alt+Delete
{shift+enter}     - Shift+Enter
{cmd+shift+f}     - Command+Shift+F

Tips & Tricks

URL Cleanup

Remove tracking parameters from URLs:

{cmd+c}{grab}{trim after ?}{paste}

Quick Navigation

Type commands with delays:

cd Projects{enter}{pause 200}code .{enter}

Text Transformation

Wrap selected text:

{cmd+c}{grab}{insert before [}{insert after ]}{paste}

Multi-Monitor Workflow

Set up Move App buttons for quick window management across multiple displays.