OmniFocus Actions Pack for Keyboard Maestro

Update 2019-08-28:

  • Corrected OmniFocusLibrary.scpt (missing argument when calling GetSelectedTasksList)

Update 2019-08-18:

  • modified method to get Message ID from note so that it works with more message: URL formats
  • possibility to specify a Task ID to get the properties of a specific task (for example Get Task Note using task ID) - if no ID is specified, the properties of the first selected task will be returned, as before.
  • possibility to set the context or project for the first selected task, last selected task, all selected tasks or specified task id.
  • See also the additional Mail Actions Pack below in this post.
  • As of 2019-08-18, this version hasn't been tested as thoroughly as the previous one, so if you want stability use V1.

Today I'm sharing my OmniFocus Actions Pack that I use daily. It works with OmniFocus 3. It offers the following actions:

  • OmniFocus Defer to Hour: sets the selected task's Defer Hour. If the defer date was in the past, set it to the next future occurence of the specified hour. If the defer date is in the future, only change the hour.
  • OmniFocus Deselect All Sidebar Elements: deselect all sidebar tree elements (if a tree is available).
  • OmniFocus Due on Hour: same behaviour as Defer to Hour, but for the due hour.
  • OmniFocus Get List of Selected Tasks: get the list of IDs of currently selected tasks.
  • OmniFocus Get Task File Path: if a file:// url exists in the note field of the first selected task, returns its POSIX path (may fail if special characters other than space %20 are present in the file path).
  • OmniFocus Get Task Mail Message ID: if a message:// url exists in the note field of the first selected task, returns its ID. Only works for links to Apple Mail messages.
  • OmniFocus Get Task Name: returns the name of the first selected task.
  • OmniFocus Get Task Note: returns the note of the first selected task.
  • OmniFocus Get Task Primary Tag Name: returns the primary tag name of the first selected task.
  • OmniFocus Get Task Project Code: returns the first word of the project name, assuming it is a project code.
  • OmniFocus Get Task Project Name: returns the name of the project of the first selected task.
  • OmniFocus Make Task: make a new OmniFocus task. You can specify its name, note, context and project.
  • OmniFocus Select Sidebar Element: select the sidebar element passed as argument. It can be a context or project, but it has to be valid for the current view.
  • OmniFocus Set Context: deprecated, it's better to use set Primary Tag instead.
  • OmniFocus Set Perspective: sets the perspective of the front window.
  • OmniFocus Set Primary Tag: sets the primary tag of the selected task.
  • OmniFocus Set Project: sets the project of the selected task.


  • Uncompress the OmniFocusLibrary.scpt file, and copy it to ~/Library/Script Libraries/
  • Uncompress the Keyboard Maestro Actions, and copy them to ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions/ — alternatively, drag and drop the .zip archive on the Keyboard Maestro Icon in the Dock.
  • Quit and relaunch Keyboard Maestro.
  • Optionally, you can install the Palette Demo Macros Library to help you start (double-click on the file, then select it in the macro library window and click on insert).

You can also call the procedures from the AppleScript OmniFocusLibrary directly.

I use these actions in a Macro Palette offering shortcuts for common things, like setting a context, a project or deferring a task to the afternoon. Using the Set Perspective, Deselect All Sidebar Elements and Select Sidebar Element actions, I can create a "smart" perspective, that will select tags based on the availability of an internet connection, my physical location, the Mac I'm currently using, the time of the day, or any other condition that you can define in Keyboard Maestro.


V2 (updated 2019-08-18) (482.0 KB)
OmniFocus Actions (5.2 MB)

V1 (original, pre 2019-08-18): (472.3 KB) OmniFocus Actions Pack for Keyboard Maestro (5.6 MB)OmniFocus Palette Demo Macros.kmlibrary (177.3 KB)


I am not able to get this working as you outlined

Can you tell me a bit more about your problem? What have you done, and where exactly is it failing?

I did not have the folders in the path you listed and had to create and move the files.

I restarted KM and not able to find the script to run

MacOS - 10.14.5
KM - 8.2.4

The elements are in the right location. Now:

  • Create a new macro in Keyboard Maestro
  • Click on Add Action
  • You should be able to find the actions in Keyboard Maestro in the "Third Party Plugin" category (see screenshot). Note: you will see more third party actions in my screenshot, the action pack only includes the OmniFocus actions.

I have also added an OmniFocus Palette Demo Library in my original post to help you get started (see original post).

I must be doing something wrong, as I do not have the 3rd party smart folder like you do....


You're showing the list of existing macros. What you need to do is:

  • Create a new macro: click on the "+" button under the "Macros" column.


  • Give a name to your new macro.
  • Now, click on the "+" button under the new macro, or on the "New Action" button.

In the actions list that will pop-up on the left of your new macro, you should have the Third Party plugin category. You may need to scroll up to see it.

THANK YOU! I am new to KM and this helps so much!!!!


Many thanks for your pack.
I have been researching different todo type applications that I can interact with Mail.
Being able to use message IDs and scripting was important to ease the interactions between the 2 programs.
Your pack gave me the incredible start I needed to move forward.

You have some other macros shown above regarding mail.
Would you be able to share them also?
Anything to help bridge the 2 apps together would be great.


[Updated to include 2 actions to get IDs and URLs of selected messages, also updated so that list items are separated with new lines instead of commas, so that it is easier to process list items in Keyboard Maestro.]

Hi Brett, sorry for the slow reply, I was on holiday, without a computer.

Here is the Mail Actions Pack, it is similar to the OmniFocus Actions Pack: you have to:

  • Uncompress and copy the MailLibrary.scpt in ~/Library/Script Libraries/
  • Uncompress and copy the Mail Actions Pack actions to ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions/

This pack provides five actions:

  • Mail Get IDs of Selected Messages
  • Mail Get URLs of Selected Messages
  • Mail Forward Message with ID
  • Mail Open Message with ID
  • Mail Reply To Message with ID (with Reply to All option)

I have included four macro examples in the OmniFocus Palette Mail Macros.kmlibrary Library.

You can get the unique ID of a message with AppleScript. Or you can use the provided Keyboard Maestro Action "Mail Get IDs of Selected Messages". To get the URL of the currently selected messages, simply use the Keyboard Maestro Action "Mail Get URLs of Selected Messages".

A bit of explanation:
The Mail message ID is extracted from a Mail message URL with the following format: message://%3cmessageID%3e for example message://%3cwT7bskxLPA@ismtpd0027%3e - the message://%3c and %3e tokens are used to find the message ID. This means that for these macros to work, your OmniFocus task should have a valid message://... URL in its notes (see screenshot below). It doesn't have to be the first line in the note.


See attached script "rule → omnifocus.sendto.scpt" as an example. This is the script that I use to send every unread Mail message to OmniFocus Inbox (I trigger it with Keyboard Maestro when OmniFocus comes to the front). It is unlikely to work as is, you'll probably need to adapt it to your specific environment. See screenshot below for the Keyboard Maestro script that I use to trigger it.

I hope this helps.

OmniFocus Palette Mail Macros.kmlibrary (78.0 KB) (478.2 KB)
Mail Actions Pack for Keyboard (2.3 MB)

Am I correct in thinking that the Mail actions only work if the original mail is in the INBOX mailbox? I have a weird setup, involving (among other things) Sanebox, and some of my mails are stored in a SaneLater box. The KM Actions you offer as demo (for mail) don't seem to find the emails even though there is a message:// url in the notes (and it opens the proper mail if I click on it ...)

Can you let me know which action exactly doesn't seem to work as intended? Can you also provide me with an example of the message:// url you're using? You can remove part of the ID if you're concerned with confidentiality, but please leave the beginning and end of the URL so I can check if it's not a url format problem, in particular I need to check that there are "%3c" and "%3e" at the beginning and end of your message ID.

Below is a macro example I use to reply to a mail from OmniFocus.

  • I select the task in OmniFocus containing the Mail message URL in its notes.
  • I trigger the Macro from a Keyboard Maestro palette in OmniFocus (see below). Note that the macro should be triggered with OmniFocus in the foreground, not Apple Mail.
  • It should create a reply message to the original message.
  • Note the trick I use to make sure that the reply window is brought to the front and is not hidden by the main Mail window.


Here's the message id: message:<1f807b8d-30cc-4b7b-9fea-fbb8d6131a6d%40Spark>

I think it's well formed. I used the Reply To macro you've set up in the examples.
I'm attaching the error message.

There were two problems (I knew the Mail Actions Pack was not really ready for wider use, this is why I didn't post it initially):

  1. I hard coded "Inbox" in the code to find the message. I did it originally because Mail's AppleScript performance is disastrous, and restricting the search to some mailboxes / accounts helps. This should be corrected in this new version, you can now specify an account name and mailbox name to restrict the search, but you don't have to (in that case the script will search every account and every mailbox until it finds the message with the matching message id, be warned that it may take a very long time, there is another method, open location, which is faster, but unfortunately doesn't allow me to do exactly what I want with replies and forwards).
  2. There is more than one valid format for message urls (crazy, I know). message://%3c...%3e, message:%3c...%3e, message://<...> and message:<...> are all valid formats. I only coded the first one (message://%3c...%3e). I added more parsing delimiters, and the other formats should be recognized (I didn't test them all!!!)

To make it work, you will need to:

  • update to V2 of OmniFocusLibrary.scpt and OmniFocus Actions Pack (see first post update)
  • update to this version of MailLibrary.scpt and Mail Actions Pack

I hope the move to the new versions goes smoothly, sometimes AppleScript keeps outdated versions of the library procedures stored in the compiled version of the scripts. (480.2 KB)
Mail Actions Pack for Keyboard (2.3 MB)

Don't forget to stop and relaunch both the Keyboard Maestro Engine and Editor. If you have the new version, you should see the new fields Account Name and Mailbox Name in some Mail actions, and the field Task ID in OmniFocus actions:

Thanks for posting.
I did some of my own mail scripting to do some of what you posted, but still helpful to review what you posted to move me along.
Your scripts helped me to understand the palettes better and how to implement them.

Many thanks,


I can't get it to work, either.

Is it perhaps different for KM 9?

I have created:

~/Library/Script Libraries/
~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions/

and copied the unzipped downloads there:

I then killed the Engine, and Editor and relaunched the latter:

Any help gratefully received :slight_smile:


Hi Mark, from what i see everything seems to be in the right location. If you already did quit and relaunch Keyboard Maestro, I don't see any reason why it doesn't work (it should work in Keyboard Maestro 9 too, I just tested it).

Something you can do to help me find the source of the problem is try to install another Action from the forum. If it works, then there is something wrong with my actions. If the other action doesn't work either, then we should double check your setup.

I implemented this yesterday as described, and it worked flawlessly, so it is probably a local issue?

Thanks so much for your reply!

I really appreciate your help.

I went through this process, which you describe so clearly several times. No joy.

So I searched for - and read - this page.

After I did it this way:

To install an action, download it and drop the .zip file on the Keyboard Maestro dock icon. To update an existing action, you must remove the old version from the Keyboard Maestro Actions folder first.

It worked.

Although doing that (zip onto the dock icon) did duplicate the subfolder. So I removed it.

And I correct in thinking that you really do need to create:

~/Library/Script Libraries

and put the OmniFocusLibrary.scpt file there; and not in:

~/Library/Application\ Scripts/com.omnigroup.OmniFocus3


If so, I think I’m all set, thank you.

But I do hope this will also be a small help, perhaps, to you for seeing why the method you designed it for doesn’t seem to work in all cases. At least in my case :slight_smile:

If I can look at anything else in that regard, please do say.

And - again - thanks very much!

Thanks, I've got it working now… I think!

It seems as though you do have to drop the zip onto the KM dock icon. Moving its contents into a manually-created sub-directory still always fails - at least in my case.

(I did stop both Engine and App.)

Thanks again, both!