Phoenix Documentation

The App class provides methods to retrieve, launch, and control running applications.

Warning: An App instance can become stale if the application is terminated while you hold a reference to it. Always check isTerminated() to verify the app's state.

The Window class allows you to control and query application windows. Windows exist within a large rectangle formed by combining all available screens. To position a window on a specific display, you must calculate its coordinates relative to this global rectangle using Screen functions.

Warning: Avoid keeping long-term references to Window instances, as they can become stale if the window is closed.

The Space class allows you to control and manipulate macOS spaces.

Compatibility Note: These features require macOS 10.11 (El Capitan) or higher.

Critical Limitation: Moving windows between spaces via API is not supported on macOS 13.6+, 14.5+, or 15.0+ due to Apple's API restrictions. For older versions, use moveWindows(...) or the addWindows/removeWindows pattern.

The Screen class provides access to frame sizes and screen information in multi-screen environments.

Warning: Screen references can become stale if a screen is disconnected while you hold a reference to it. It is recommended to fetch the screen instance when needed rather than storing long-lived references.

Phoenix uses a JavaScript-based library to implement API features. If you want to develop features for this library, you need Node.js (24.7.0 or higher).

Setup and Build

1. Install development packages:

   npm install

2. Build the minified library (Phoenix/phoenix-min.js) from source:

   npm run build

   This builds the source from library/src/ and installs it to Phoenix/phoenix-min.js.

Phoenix is scripted using JavaScript (ES6 supported on macOS 10.12+; ES5.1 on older versions). You can also use TypeScript or other languages that compile to JavaScript.

Configuration File Locations

Place your script in one of the following locations:

• ~/.phoenix.js (Recommended)
• ~/Library/Application Support/Phoenix/phoenix.js
• ~/.config/phoenix/phoenix.js

Available Utilities

• Lodash: Phoenix includes Lodash (version 4.17.15) by default.
• System Interaction: You can bind keyboard shortcuts and system events to callback functions to control screens, spaces, mouse, apps, and windows.

You can install Phoenix using one of two methods:

Method 1: Manual Installation

1. Download the latest archive from the GitHub releases page.
2. Extract the archive.
3. Drag and drop the Phoenix app to your Applications folder.

Method 2: Homebrew

If you have Homebrew installed, run:

brew install --cask phoenix

Important: Accessibility Permissions

When running Phoenix for the first time, macOS will require you to grant it permission to control your UI.

1. Open System Settings.
2. Navigate to Privacy & Security > Accessibility.
3. Enable the toggle next to Phoenix. Note: An admin account is required to change these settings.

Depending on your macOS version, use one of the following methods to move windows:

macOS 10.13+ (up to macOS 13.5, 14.4, or 14.9)

Use moveWindows(Array<Window> windows) to move windows to the space.

macOS < 12.0

Use a combination of addWindows(Array<Window> windows) and removeWindows(Array<Window> windows) to manipulate window placement.

Warning: Moving windows is restricted on macOS 13.6+, 14.5+, and 15.0+.

Phoenix handles two different macOS coordinate systems using the same Point type. Developers should be aware of which system is being used to avoid orientation errors:

1. Bottom-left origin: Used by higher-level macOS elements, where (0, 0) is the bottom-left corner.
2. Top-left origin (Flipped): Used by lower-level macOS elements, where (0, 0) is the top-left corner.

Important: Unless explicitly stated otherwise, the majority of the Phoenix API uses the flipped top-left based origin system.

You can debug your configuration using Safari's Web Inspector.

1. Open Safari's Develop menu.
2. Locate your device name.
3. Attach to the context to view the Web Inspector.

Messages outputted via console.log or Phoenix.log will appear in the Web Inspector's Console.

Note on Compatibility: Due to macOS security restrictions, this debugging method only works on:

• Non-notarised versions of Phoenix (2.6.2 or older)
• Debug builds built from the source

To build Phoenix from the source repository using Xcode, follow these steps:

Prerequisites

• Git
• Xcode 16 or higher
• Xcode command line tools

Build Steps

1. Clone the repository:

   git clone https://github.com/kasper/phoenix.git
   cd phoenix

2. Build the workspace using xcodebuild:

   xcodebuild -workspace Phoenix.xcworkspace \
              -scheme Phoenix \
              -configuration Release \
              SYMROOT="$PWD/build/" \
              clean build

For a Debug build, change the -configuration flag to Debug. The resulting app will be located in build/Release/ or build/Debug/ respectively.