George Huebner

Location-based Reminders with beorg

I was talking with my roommate about his Org agenda workflow and he noticed some “trivial” tasks cluttering his inbox. These tasks required no thought, but required being at a specific place to complete. My roommate and I both use the wonderful iOS app beorg to keep our Org files synced to our phones so we can receive reminders and file things into our inboxes when away from our computers. However, beorg doesn’t do anything special (to my knowledge) based on location; that’s fine by me, because it does one thing and does it well.

Still, this got me thinking: might there be a way to tag TODOs such that they don’t show up in the agenda view, but such that I receive a mobile notification when I’m at a location I can act on them (e.g. grocery store)? So I set out to create a workflow for location-based reminders in Org-mode.

All shortcut files used in this post, along with instructions for importing them, are provided at the bottom of this page.

Shortcuts

I had just started exploring the iOS Shortcuts app a few days prior (which I used to selectively enable a greyscale filter in unproductive apps), and it seemed like this would be up to the task. Trigger a workflow on arrival to any location? Oh, this will be a breeze!

If only we knew the suffering that would befall us next…

The first piece of the puzzle was figuring out how to activate a shortcut when I arrived at certain location: this in and of itself was not too hard to do, using personal automations. You provide a trigger, and run an automation; it’s annoying you can’t call the automation with arguments (besides your location, I mean), but you can define wrapper shortcuts that call a location agnostic shortcut with a particular string, for example.

The second piece of the puzzle was getting the important information from beorg; naturally, the author of beorg being a Lisp programmer and all, beorg has a very comprehensive scripting API and IPC interface (which he used to make his own org-capture shortcut for Safari!) The part I care about are URL Schemes, which allows using the “Open X-Callback URL” action to perform certain actions in beorg, like adding agenda items or searching the agenda. Using the basic beorg search syntax, k r location home will search for incomplete items that have the property location with value home (both are case insensitive).

(Oh, and don’t bother with the “Show Alert” action, because you can’t customize the display or make it do anything useful when clicking on it.)

This works great, except there was a small problem: this only works when my phone is unlocked. I guess executing arbitrary code without user interaction is no bueno™, after all. So when I walk into my lab, instead of a helpful reminder all I get is a prompt for my password. Even worse, this prompt shows up every time I trigger the reminder, because it needs to unlock my phone to run the query, regardless of whether that query returns an actionable task or not.

It was time to go back to the drawing board.

Shortcuts, take 2

My thought process was this: I don’t actually mind unlocking my phone to see the specific agenda items in beorg if I know there will be items; would it be possible to just check for the existence of location-based reminders without unlocking my phone?

This is where this endeavour goes from neat to completely scuffed.

Not every action in a shortcut requires unlocking the phone; it turns out that although you can’t open other apps, you can read files. All of my Org files are stored in my iCloud Drive, so I can read them from the shortcut no problem. The dumb (and, as it turns out, best) idea is just using a regex to search for the value of the LOCATION property (this does require that I’m diligent about refiling DONE items so the only items with the LOCATION property set in my agenda are incomplete). This approach doesn’t require PCRE or lookahead to gather information about the task—once I know the task exists, I can just check my agenda for more details.

So running this manually on my laptop works fine; great.

Now on iOS… hmmm. That’s not right.

The content graph on MacOS looks fine (I can even export my Org files to PDF!), but iOS refuses to treat the files as text.

I almost gave up here after being unable to do something as simple as write a file… iOS was very picky in what constituted a “valid path”, a problem likely exacerbated by the fact I’m mucking around in my iCloud Drive. But I found a shortcut someone else wrote for dumping binary media that gave me the idea to base64 encode the Org files, which should work on any arbitrary bytes, regardless of filetype. So I literally just fed the “Encode with base64” shortcut into the “Decode with base64” shortcut, and… viola! We have our file!

The only minor hiccup I encountered was opening the X-Callback URL would switch to the beorg app, but then immediately switch back to Shortcuts. The fix was opening the URL with the “Open URL” action instead of the “Open X-Callback URL” action, which still pulls up the agenda search view as desired.

Now we’re done.

Finishing up

When I was writing this up, I wanted a way to easily share the Shortcut (especially because it uses this block-based language that’s really annoying to edit). You can share shortcuts through iCloud, but I literally just want a plaintext file. Trying to export a shortcut to a file will either phone home to Apple or forcibly sign it with your contact information.

The workaround I found was thus:

  1. Write an auxillary shortcut that exports shortcuts to p-lists, and run that on the shortcut you’d like to export
  2. Change the extension (of the p-list which is actually XML) from .xml to .shortcut

This gives you an unsigned shortcut, but you can’t import those; the receiving party must:

  1. Run shortcuts sign -m people-who-know-me -i input.shortcut -o output.shortcut (this signs output.shortcut with your contact info, but you can keep this as device-local copy). Oh wait, that doesn’t work! The example I literally copy and pasted straight from the docs doesn’t work! Give up and resign yourself to signing with anyone instead.
  2. Double-click output.shortcut or drag it into the Shortcuts app to import it (for some reason the “File > Import” menu bar item doesn’t seem to recognize these).

In summary:

Shortcuts

#org