Using Workspaces

Workspaces is a versatile program with that is designed to facilitate the starting up and shutting down of programs for different workspaces. This tutorial will cover the installation of Workspaces, setting preferences, installing plugins, creating workspaces and resources to optimize context switching, and using Workspaces to achieve the best results.

Installing Workspaces

The Workspaces Website is a great place to download the application for trying out this tutorial. It gives a 30 day trial period where you can try out the application and all of it's features. It is more than enough time to really get used to the program and how it works.

If you are certain you wish to use it, you may purchase it from the MacApp Store. This option does not provide a trial period, however, as it is updated on the app store, it will also be updated on your computer.

SetApp is an annual subscription-based platform that provides access to over 240 macOS applications, including Workspaces. With one yearly fee, users can enjoy the convenience of having a wide range of programs at their disposal, making the macOS computer experience more efficient and cost-effective. SetApp will ensure that your system is running optimally by automatically updating the programs to their latest version.

Overview of Workspaces

When Workspaces is loaded and launched on your computer, it adds an icon the shape of a wrench to the menubar.

Workspaces Menubar Icon

Clicking on the icon will bring the main application window to the center of the current screen, or to the last location that the window was moved to.

This main application window displays a list of workspaces, with a command line at the top. The command line is automatically selected, allowing users to type in a workspace to open or resource to launch. Additionally, clicking on a workspace will open the associated resources list. Pressing Start will launch the resources that have been marked to launch upon starting.

The command line allows the use of special commands prefixed with the : (colon), such as: quit, edit, preferences, new, help, about, start, sort, archive, and unarchive. Additionally, plugins can add to this list of actions. These command line actions are intuitive and highly beneficial once mastered.

To begin, configure your preferences for using the program. Click the circle with three dots at the lower right of the window to open the application menu. Select Settings... to open the settings screen.

Workspaces General Setting

The top row of the preferences contains five sections. By default, the General preferences are displayed, where the application can be configured to open automatically, the appearance can be set to either light, dark, or the current system preference, the workspace to open on application start can be specified, and the default terminal and file manager to use can be selected.

Workspaces Editor Setting

The Editor preferences allows the setting of the editor window to be above everything or not. It's best to keep it always on top because it will the be above the application window. If it's not set to be on top, the applicaton window will block the editor window until you dismiss the application window.

When adding resources to a workspace, it can be set to be opened by default automatically with the second option checked. This makes adding default launching resources easy to create. But, it might be in the way if most resources aren't being launched upon opening a workspace. It all depends on individual use patterns.

The last option allows for a hotkey to open the editor window for the currently open workspace. This can be very handy when working in a workspace and realizing more resources should be added for that workspace.

Workspaces Search Setting

The Search preferences allow the user to customize the appearance of the main application window, commonly known as the search window due to its primary purpose. This is the main area where most of the program's activities occur.

Users can select between Full or Minimalistic mode; Full displays all available options in the user interface, while Minimalistic only displays items that are not easily accessible through keyboard shortcuts.

The sorting order for workspaces in the window can be set to Don't Sort, By Name, By Mostly Used, or By Recently Used. Selecting Don't Sort will display the workspaces in the order they were created.

The Behavior section allows the setting of three types of behaviors: Close after launching a resource manually, Open workspace with a single mouse click, and Open resource with a single mouse click. All of these are straightforward and easy to understand. When configuring workspaces in Workspaces, it is recommended to not select the first option in order to keep the window open and make further modifications when testing a new workspace.

The next section is Open or Hide, which enables you to assign a hotkey for opening or hiding the Workspaces main window. This is a very useful feature and should be configured. Once it is set up, use it regularly to open and close the window to develop muscle memory for it.

Workspaces Plugins Window

The Plugins section of Workspaces allows for the configuration of its five plugins: AddResources, ScriptRunner, QuitApps, PlayMusic, and Keystroke. To obtain a plugin, simply click on the Get Plugins text at the lower right of the dialog, which will open the system configured web browser to the download page. After downloading the desired plugins, unzip each one and press the + text at the bottom left corner of the dialog to select the plugins to install in the Open File dialog. To remove a plugin, select it from the list and press the - text.

The circle with the three dots allows the plugin to be configured. Currently, only the ScriptRunner and QuitApps are configurable.

AddResources Plugin

The AddResources plugin adds the add command in the command line of the search window. This allows the adding of resources to a workspace much faster. When :add is typed in the command line with a space, a list of options is given: add apps, add chrome, add finder, and add safari.

Add App Command List

The 'Add Apps' feature enables the selection of one or more currently open applications to be added to the current workspace. This plugin doesn't have anything to setup in preferences.

The :add other options enable the installation of the current window of the specific application as a resource in the current workspace. For example, if Safari is open to the Apptorium website, a resource to open that site will be added to the workspace. This feature is an efficient way to set up browser locations or Finder folders for each workspace.

ScriptRunner Plugin

The ScriptRunner allows the running of a shell script routine. This can do anything that a shell script can do. But, the path for searching for commands needs to be setup first. To do that, open the preferences for ScriptRunner:

ScriptRunner Preferences

The input for Set $PATH to: needs to be set for the different paths used for your script. You can always go to a terminal and execute env | grep "PATH" and copy the text after the = sign for PATH and paste it in to this input.

The section Default script options: allows for the customization of when to show results, show notifications, and a default timeout, depending on the user's needs. The show results and show notifications can be set to: always, On errors, or never. During the development of the script, the always setting is highly recommended; otherwise, the On error setting is likely sufficient.

QuitApps Plugin

The QuitApps plugin is a great tool for streamlining your system and ensuring that unnecessary applications are not running in the background. It allows you to set up a default configuration of applications to quit when leaving a workspace, and automatically populates the QuitApps resource with these applications. This helps to keep your system running as efficiently as possible.

PlayMusic Plugin

The PlayMusic plugin enables users to select from preconfigured playlists on the Music program and play music while running a workspace. Depending on the user's preference, the plugin can be set to Pause to turn off music playing. This plugin doesn't have anything to setup in preferences.

Keystroke Plugin

The Keystroke plugin causes a particular Keystroke to be simulated when the resource is launched. This plugin doesn't have anything to setup in preferences.

Workspaces Data Preferences

The last preference is call Data. In this dialog, the user can inport data from 1.5 version of Workspaces or simply open the folder that contains Workspaces data file. If you are restoring data file that was previously saved, make sure the program is completely closed before moving the data files.

Creating a workspace

The heart of Workspaces is the workspace. Each workspace represents a state of the computer for the type of work. The workspaces can be named anything, just be fairly discriptive.

Workspaces Project Window

In the main workspaces window, a list of workspaces is presented. To initiate a workspace, press or select the workspace, press Enter, and then press Start button on the upper right of the workspace screen. To create a new workspace, simply press the Edit text in the upper right corner or use the hotkey assigned in the General preferences section.

Workspace Edit Window

In the Edit window, new workspaces can be created by pressing + in the lower left corner under the list of workspaces already created. This creates a new workspace with the name New Workspace highlighted; simply type the desired name of the workspace. The next column contains a list of resources for the currently highlighted workspace.

Workspace Add Resourse

By clicking the + under that column allows for the addition of different resources, such as files, folders, websites, e-mails, applications, terminals, URLs, actions, or shortcuts. It should be noted that the Website and URL options are not redundant; Website allows for the selection of a browser to use, while URL only opens with the system-configured browser. A separator can be added between resources to better organize the layout of the resources.

Workspaces Add Action

If an Actions is added, a list of possible actions from plugins is shown. This is the main function of plugins.

Workspaces Add Shortcuts

If a Shortcuts is added, a list of Shortcuts defined by the Shortcuts program is shown. Just select the Shortcut needed and it will be added as a resource for that workspace.

Default Workspace

Since the interface has been fully described, create a workspace named Default. This workspace should launch all necessary programs when the computer is started. Once the workspace has been created, set it to Launch on Startup in the General Preferences. This will ensure that all resources in the workspace are launched each time Workspaces is opened. If Workspaces is set to open on login, it will launch each resource in the Default workspace each time you reboot the system.

Next, populate the workspace by pressing the + button and adding the resources to run. Applications are beneficial, however, a default website opening to a news site could be advantageous. Additionally, a Shortcut or a ScriptRunner can be added to position the windows and perform other default activities that are useful.

Writing Workspace

Create a workspace titled Writing to setup the computer for tech writing. Include a text processing program, such as Yank Note, and an outline manager program, such as Bike. This may need to be modified to the programs that are best suited for the task.

To add Shortcuts for the layout, you can see it in detail in the tutorial Using Shortcuts. But, this can also be done using a ScriptRunner resource.

ScriptRunner Resource

In order to run the script when the workspace is started, the Launch attribute at the bottom should be set to on start. To ensure the script arranges application windows that are being launched, click on the immediately text and change it to with delay, setting the time to 5 s. This can be tested and adjusted to the minimum time necessary for waiting on the applications to launch. This time period will depend on the computer being used and the application launching taking time to settle down. To create the script to be ran, press the Edit button.

ScriptRunner Editor

The ScriptRunner editor window is minimalistic, with a side ways triangle button to run the script. The circle with three dots sets the preferences, as previously outlined in the tutorial, and the values set in the preferences will appear here and can be modified for each script. Underneath the title bar is the editor, where the shell script for the user's default shell is written and edited. The script needed is:

hs -c "setWritingWindows()"

This script depends on Hammerspoon to move the windows into position. The easiest way to install Hammerspoon is with Homebrew. Install Homebrew and run the command:

brew install Hammerspoon

The Hammerspoon install needs to create a cli in your home directory in order to use it. By running the commands:

mkdir ~/bin
ln -s /Applications/ ~/bin/hs

In the ScriptRunner preferences, add the ~/bin directory to the PATH line. To configure Hammerspoon to position the windows, edit the Lua script located at $HOME/.hammerspoon/init.lua and include the contents as follows:

-- Function:           setSize
-- Description:     Resize the current window by pixels and optionally
--                  set the position.
function setSize( width, height, x, y )
   local win = hs.window.focusedWindow()
   local f = win:frame() = win
   saved.winframe =
   f.w = width
   f.h = height
   if x ~= nil then
    f.x = x
   if y ~= nil then
    f.y = y

-- Function:    focus
-- Description: This function will unminimize the given app and focus it.
function focus( app )
    hs.appfinder.appFromName( app ):activate()

-- Function:    SetWRitingWindows
-- Description: Set the size and position of the windows for doing Tech Writing.
function SetWritingWindows()
    focus("Yank Note")

Once you have restarted Hammerspoon, your ScriptRunner script should be operational. To ensure this, please make sure that the location of the Hammerspoon cli (hs) is included in the PATH statement in the preferences, as previously mentioned in the tutorial. Hammerspoon and Workspaces can be combined to create powerful workflow improvements. The only limit is your imagination.

Programming Workspace

I like to program using Neovim. This is a terminal editor that is very fast and very versatile. So, to create a workspace for working on a program, create the EmailIt workspace (that is the name of the workspace I'm working on). Then add a terminal resource with the path set to the directory of the workspace by dragging the folder from Finder to the resource. This will launch the terminal set to that path.

Next, create a ScriptRunner resource to run this command line:

cd ~/<path to project directory>
wails build

This project is a Wails project that this script will compile. The <path to workspace directory> has to be set to the proper path. The ScriptRunner scripts know nothing about where the projects are located. Therefore, the script has to first go to that location on the harddrive. Then it compiles the program. Set this script to always show the output so that you can watch and know when it is finished.

Next, add a QuitApps resource and set it to close the iTerm application and the EmailIt program. Then set it to Launch on finish.

Programming Workspace Finish

Create an application launcher for the program that does not automatically launch, and add descriptive separators to enhance the visual appeal. The workspace should appear as follows:

Programming Workspace

Working With a Workspace

Now that the programming workspace is setup, let's go through a typical session. First press the hotkey to bring up the workspace window. On my system it's ---. In the command line, type :start EmailIt and press . The terminal will launch and move into position, but the compiling and launching of the program didn't run. That's because they are set to manual and only run when selected.

Once some programming has been done, open the workspace window again and type build EmailIt. The resource will appear in the list highlighted with just the bui. Press the key and the building script will run showing the results of building in a window. When done, you can launch it just by typing emailit, once, and (of course, your workspace names will be different).

When transitioning to a different workspace, the QuitApps will close the terminal and program. This provides a convenient way to keep the computer organized.

Making workspace Notes

In the workspace view of the program, the icon in the lower left corner toggles the notes sidebar to the workspace. This is very handy way to keep up with things to do in the workspace.

workspace Notes

It uses the same markdown approach that Side Notes uses. The check boxes in the picture above are done with square brackets with a space in the middle (ie: [ ]). When you click on it, it will toggle between checked and unchecked states. By clicking on the Aa at the bottom right corner of the notes area, you can see the list of markdown syntax to insert to the current cursor location.

If you need more notes, you can use Side Notes with Workspaces by dragging a Side Notes folder to the resource area of a workspace in the workspace editor. When you launch that resource, the notes in Side Notes is opened.

Other Ideas

workspaces can be created to store URLs, applications, and files that are frequently used. The workspace window provides an easy way to launch them by using the command line in the window.


Workspaces can be automated by external programs very easily. In the workspace editor, right click on the workspace name and select the Copy URL menu entry.

Project URL

This will copy an URI for the workspace that can be used to start the workspace. The file manager that I use is called Modal File Manager. It has an extension call workspace Manager that will run a script when I enter the workspace directory in Modal File Manager. In this script, I place this line:

open workspaces://start/255F71B7-81C6-43E9-B9C7-D89583F14201

By navigating to the workspace directory in Modal File Manager, the workspace resources are automatically launched and the workspace is set as the active workspace. This automation saves time, as I no longer need to manually launch the workspace when working on it.


Workspaces is a powerful application that offers users a comprehensive solution for organizing and managing their workspaces and resources. With its user-friendly interface, Workspaces is a valuable tool for enhancing productivity and organization.