Mac OS X: Automating Tasks on Sleep

I’ve been playing a lot lately with AppleScript and the Mac Automater app, both of which can do some pretty cool stuff. This gave me an idea: wouldn’t it be great if I could close certain applications when my commuters go to sleep?

I have a handful of programs that I run on both my MacBook and Mac Pro desktop at work, using file syncing tools like Dropbox or BTSync to keep the data files up to date on both machines. This generally works great, except that I have to remember to close the programs when I switch machines, otherwise I sometimes end up with unexpected results like locked files or, in some cases, data loss. I’m not so good at this and Apple doesn’t appear to provide a way to do it for me.

It didn’t take long, however, to find a free third-party utility that does. Sleepwatcher is a small daemon process that monitors the sate of your system and kicks off a shell script when certain system events occur. It can monitor for events such as sleep and wake up, display sleep and dimming, and even system idle (a specified period with no keyboard or mouse activity) and power status (when a MacBook switches from AC to battery power and vice-versa). It can also prevent the machine from sleeping based on the result of a script or it can run a script when another process prevents the system from sleeping. Sleepwatcher can be run as a system process (always running in the background, even when no users are logged in), as a user process for individual logged-in users, or both.

Before we get too far along, it should be noted that this may not be the best approach for all applications. The method I’m about to describe works best with applications that save their data files automatically, and exit without user intervention. While the applications will be shut down in a clean manner, you may have unexpected results if the application prompts you to save or to confirm that you really want to quit.

It is also very important to note that you should be extremely careful when implementing these scripts. An improper configuration could render your machine unable to sleep, wakeup, or even boot, so be sure to carefully test your scripts before enabling them to run automatically.

Installing Sleepwatcher from the developer’s site is a bit tricky as it comes with no installer and assumes some knowledge of the Unix command line. A much easier way to install it is to use a package manager such as Homebrew (I believe MacPorts can also install Sleepwatcher, but I’ve only done it with Homebrew). If you aren’t familiar with Homebrew, it is definitely worth checking out.

Assuming that you have Homebrew installed and working correctly, installing Sleepwatcher is as easy as running the following command in a terminal window:

brew install sleepwatcher

Homebrew will download and install Sleepwatcher at /usr/local/sbin/sleepwatcher. Note the followup instructions that Homebrew provides after installation, as we’ll get to them in a moment. Once the installation is is done, I recommend reading the man page, as it is the best way to get to know everything Sleepwatcher can do:

man sleepwatcher

Now it’s time to write a sleep script. As we’ll find out in a moment, Sleepwatcher looks for user scripts named ~/.sleep and ~/.wakeup and system scripts named /etc/rc.sleep and /etc/rc.wakeup. Since we want to close programs that are running under our own UID, let’s choose the local user option.

First, create a file named .sleep in your home directory using your editor of choice (mine is vi for this kind of stuff):

vi ~/.sleep

Then add the following to the file (in this example, I’m going to close the program KeePassX, my password manager, using AppleScript):

#!/bin/bash
osascript -e 'tell application "KeyPassX" to quit'

If you want to close additional applications, simply add another osascript command for each additional application.

Why use AppleScript instead of something more bash-like, such as kill? AppleScript works inside the application, telling it to do a clean exit, such as if I pressed Comand-Q to close it myself. This allows the program to make sure files are saved and everything is in order before the process ends. Kill simply aborts the running process, regardless of what’s happening, which could result in data loss and other instabilities, which we’re trying to prevent in the first place.

After the script is saved, you’ll need to give it execute premissions:

chmod 700 ~/.sleep

New we’re ready to test the script. Enter the following in a terminal window to start Sleepwatcher:

/usr/local/sbin/sleepwatcher --verbose --sleep ~/.sleep

You won’t see anything happen; in fact, it will look like the terminal is hanging. Make sure KeePassX (or whatever program you added to the .sleep file) is running and then close the lid of your MacBook (or go to Apple Menu > Sleep if you aren’t on a MacBook). Wait until the computer’s power light starts to slowly blink on and off, and then wake it by opening the lid and/or pressing the power button. The computer should resume exactly as you left it except that your target application should no longer be running. If anything went wrong, check the terminal window where you ran Sleepwatcher, it should show any errors that occurred. Press Control-C to stop Sleepwatcher.

Now it is time to configure launchd to run Sleepwatcher at startup or login. To do this, we need to add a plist file to our user or system’s LaunchAgents directory. Sleepwatcher comes with sample plist files that handle the four use cases mentioned above: user sleep, user wakeup, system sleep, and system wakeup.

If you only need support for sleep and wakeup, you can simply symlink the sample files to the proper LauchAgents directories. For this activity we only need to set up the user LaunchAgent since we aren’t using any system scripts:

Note that you’ll need to be an administrator of the machine to install the system agent.

That’s about all there is to it! Sleepwatcher is now running in the background waiting for your computer to go to sleep. When they system does, Sleepwatcher will kick off your .sleep script and, when the system resumes, Sleepwatcher will run your .wakeup script (if you create one). And, since you also added the plist file to your LaunchAgents directory, launchd will find it and start Sleepwatcher every time your machine starts up or whenever you log in.

If you want to script other events, such as system idle or power status, you’ll need to make a copy of the sample plist file(s) and edit them by hand. Understanding the plist file format should be fairly straightforward if you compare the sample with the options described on the man page. Xcode features a graphical plist editor, but plists are simple XML files, so you can edit them in any text editor if you prefer.

Do you have a creative use for Sleepwatcher? Let me know about it in the comments.

Hi, this is a great article as I am trying to replicate a similar event on waking up my mac from sleep. I am running OSX EL Capitan – and for some reason, when I awake from a sleep state, the mail app is active on my desktop, even when the window is closed (but active in the dock). Not sure if this is a bug, but I haven’t been able to find any way to fix this other than running sleepwatcher until apple figures out the issue. I have installed Sleepwatcher correctly, typing “man sleepwatcher” I do get a text return in terminal. I have made a .”wakeup” file in my home location (/Users/GHOST/hidemail.wakeup/hide\ mail.scpt) and have written my script to hide mail:
tell application “System Events”
set visible of process “Mail” to false
end tell
– and saved it to the .wakeup file in the home location. I am not sure where to take it from here. I understand I need to add the plist file to the launch agent directory, just not sure what the plist should show? Thanks in advance for the help.

.wakeup file is not a file extension, it is the name of the file you should be using for your script. In Unix-based systems, any file that starts with a period (commonly called “dotfiles”) are normally hidden from directory listings. They are generally used for configuration files; since they’re hidden, they’re less likely to get changed or deleted accidentally.

When you symlink the “localuser” plist, it already has support for .wakeup scripts (as well as .sleep) so there’s nothing more for you to do. Sleepwatcher also supports a handful of other system states, such as display sleep, which are not mapped to script names in the default plist, so if you want to use any of these, you’ll need to edit the plist file. But if you’re content with just “sleep” and “wakeup,” you can follow my tutorial exactly as I wrote it.

SleepWatcher was developed by Bernhard Baehr. You can find it on his website at http://www.bernhard-baehr.de/. I don’t know if it’s open sources, though Baehr does provide a link to the source of an older version on his site. I’m not sure if/where SleepWatcher logs script output as I only use it with simple scripts that produce no output.

Super useful, thanks Kodiak! I had the exact same use case, using DropBox as a “backend” for my KeePassX files. Not sure what I did wrong, but I had to deviate from your .sleep structure slightly to get it to work:

Sorry for taking so long to reply. Unfortunately, I don’t believe there is a way to trigger sleepwatcher when the screensaver activates, but there are a couple of workarounds. For either of these, you’ll need to modify the default .plist file that comes with sleepwatcher since that file only supports “sleep” and “wakeup” functionality. To do this, I’d recommend copying the default file instead of linking it, as I did in my original post, so to prevent an update from overwriting your changes down the road.

Then open the ~/Library/LaunchAgents/de.bernhard-baehr.sleepwatcher-20compatibility-localuser.plist file with XCode, if you have it installed, or your favorite text editor. You’ll see two lines in about the middle of the file that look like this:

-s ~/.sleep-w ~/.wakeup

These are the arguments passed to the sleepwatcher command when you log in that instruct it on what system events to monitor. Simply add additional blocks below those two lines with additional arguments to monitor different events.

The two events you may want to consider are Display Sleep (-S) and Idle (-i).

Display Sleep is triggered when the computer’s display goes to sleep, which you can configure in the Energy Saver pane in your System Preferences. Display sleep generally kicks in a while after the screen saver does (otherwise you’d never see the screen saver), but this may be an acceptable work-around, depending on your application. To monitor display sleep, add the following to your plist file:

-S .displaysleep

If you need your script to run sooner than when the display sleeps, you might consider using the Idle monitor, which kicks in after a specified duration with no keyboard or mouse activity. If you set it to the same duration as your screensaver timeout, you should get a result that’s pretty close to perfect. The idle argument requires a second timeout argument, so add both of these to the .plist files, replacing the XXXX in the second line with your desired timout. This value is counted in tenths of seconds, so for one minute use 600, for ten minutes use 6000, etc.

-i .idle-t 6000

You may also want to add arguments for display wakeup (-W) and idle resume (-R), but I’ll let you figure those out yourself.

Once you’ve edited and saved the .plist file, you’ll need to reload it for your changes to take effect. To do this run these two commands in a Terminal window: