Skip to content
A lightweight macOS/OS X window and app manager scriptable with JavaScript
Objective-C JavaScript Shell Ruby
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github OS X to macOS (#104) Jul 7, 2016
Phoenix.xcodeproj Ensure NPM dependencies are installed before building (#232) Jan 13, 2019
Phoenix.xcworkspace Upgrade to Xcode 9.3 Apr 2, 2018
Phoenix Add new EdDSA public key for Sparkle Dec 28, 2018
PhoenixTests Upgrade to Xcode 7 Sep 24, 2015
assets Add screenshot assets for using Web Inspector Apr 15, 2018
docs Add support to load images from files which can be used as custom ico… Dec 28, 2018
library/src Replace JSHint and JSCS with XO and ESLint Dec 26, 2018
.gitignore Remove Grunt Dec 26, 2018
.ruby-version Upgrade Ruby to 2.5.3 Dec 25, 2018
.travis.yml Remove Grunt Dec 26, 2018 Fix an issue that caused a crash if accessing screens for a space und… Dec 28, 2018
Gemfile Upgrade Ruby to 2.5.3 Dec 25, 2018
Gemfile.lock Update gems Dec 25, 2018 Replace Underscore.js with Lodash (#89) Nov 12, 2016
Podfile Upgrade Sparkle to 1.21.2 Dec 25, 2018
Podfile.lock Upgrade Sparkle to 1.21.2 Dec 25, 2018
package-lock.json Replace JSHint and JSCS with XO and ESLint Dec 26, 2018
package.json Replace JSHint and JSCS with XO and ESLint Dec 26, 2018
release Create EdDSA signature in release script Dec 29, 2018
sparkle.xml 2.6.2 Jun 7, 2018


Build Status


A lightweight macOS window and app manager scriptable with JavaScript. You can also easily use languages which compile to JavaScript such as CoffeeScript. Phoenix aims for efficiency and a very small footprint. If you like the idea of scripting your own window or app management toolkit with JavaScript, Phoenix is probably going to give you the things you want. With Phoenix you can bind keyboard shortcuts and system events, and use these to interact with macOS.

  • Current version: 2.6.2 (Changelog)
  • Requires: macOS 10.10 or higher

Note: the default master-branch will always be stable.

Key Features

  • highly customisable, write your own configuration
  • bind keyboard shortcuts and system events to your callback functions
  • control and interact with your screens, spaces, mouse, apps and windows
  • log messages, deliver notifications or display content as modals
  • run external commands


To install, extract the downloaded archive and just drag-and-drop Phoenix to your Applications-folder. When you run Phoenix for the first time, you will be asked to allow it to control your UI. macOS will ask you to open Security & Privacy in System Preferences. Once open, go to the Accessibility-section and click the checkbox next to Phoenix to enable control. An admin account is required to accomplish this.

Alternatively, if you have Homebrew Cask installed, you can simply run brew cask install phoenix.


To uninstall Phoenix, delete the app from your Applications-folder. The configuration file created by Phoenix itself is located in your home folder. Delete ~/.phoenix.js and any related configurations if desired. For developers, you may also need to delete ~/.phoenix.debug.js.

If you have used the storage, also delete the file ~/Library/Application Support/Phoenix/storage.json. Again for developers, you may also need to delete ~/Library/Application Support/Phoenix/storage.debug.json.


Phoenix lives on your status bar (or as a background daemon) and can be scripted in JavaScript (or languages which compile to JavaScript such as CoffeeScript).

Screenshot of Phoenix

See the JavaScript API to get started with your script. Your script should reside in ~/.phoenix.js — the file will be created when you launch Phoenix for the first time. Alternatively — if you prefer — you may also have your script in ~/Library/Application Support/Phoenix/phoenix.js or ~/.config/phoenix/phoenix.js. For ideas, see what other people have built in their configurations in the Wiki. Feel free to add your own configuration to the Wiki to show other people the nice things you can do. Previous configurations (<= 1.5) are not compatible with 2.0, see Changelog for what changes are needed.


You will need some basic knowledge about installing the required languages and tools. If you need help, do not hesitate to ask! To get started, you will need:

  1. Git
  2. Xcode 10 or higher
  3. Xcode command line tools

First clone the repository from a terminal:

git clone
cd phoenix

To develop Phoenix, open Phoenix.xcworkspace in Xcode. Install Xcode from the App Store, if you do not already have it installed. You will also need Xcode command line tools — you will be prompted for this. Everything else should work as is — you can develop, debug, test, build and run Phoenix straight from Xcode.

To install Phoenix from the source, you will need to build the workspace from a terminal:

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

Once complete, you will find a newly built Phoenix app in build/Release/. After this, you can follow the normal install guide.

Phoenix manages dependencies with CocoaPods. Note that you do not need CocoaPods for basic development. However, if you want to install new pods or update existing ones, you will also need:

  1. Ruby (2.5.3 or higher), it is recommended that you manage Ruby versions with for instance rbenv
  2. Bundler
  3. CocoaPods

Install Bundler, if you do not already have it installed. To install CocoaPods and its dependencies, use Bundler inside the phoenix-directory to install the required Ruby gems according to the Gemfile. Once complete, you can install the pods listed in the Podfile with CocoaPods.

gem install bundler
bundle install
pod install

In addition to the Objective-C core, Phoenix also uses a JavaScript-based (5.1) library to implement additional features to the API. The minified library is included in the repository in Phoenix/phoenix-min.js so that everything works as is. However, if you want to develop features for this library, you will also need:

  1. Node.js (11.5.0 or higher)

Install the development packages listed in package.json.

npm install

To build phoenix-min.js from the source, run the command npm run build in the root directory. NPM will then build the source from library/src/ and install the new library to Phoenix/phoenix-min.js. For convenience, this is also handled automatically by Xcode when you build Phoenix.


Feel free to contribute to this project by creating issues, pull requests and editing the Wiki. See the guidelines.


If you have any questions, feedback or just want to say hi, you can open an issue, email or tweet.


Phoenix is currently developed by Kasper Hirvikoski (@kasper) and Jason Milkins (@jasonm23) with the generous help of contributions made by many individuals. It was originally authored by Steven Degutis (@sdegutis) as a fork of Zephyros — also an app of his. As it stands now, it has been rewritten from the ground up by Kasper Hirvikoski.


Released under the MIT License. See license.

You can’t perform that action at this time.