From 81bd3ac883090c1c59b35bef995e8cac6a96e312 Mon Sep 17 00:00:00 2001
From: Andrew Kwon <andrewshky@gmail.com>
Date: Sun, 3 Feb 2019 14:51:11 -0800
Subject: [PATCH 1/5] Record events and dispatch action with workflow

---
 src/entity.lua |  5 +++--
 src/init.lua   | 14 +++++++++++++-
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/entity.lua b/src/entity.lua
index f3a564f..0ac77a2 100644
--- a/src/entity.lua
+++ b/src/entity.lua
@@ -276,10 +276,11 @@ end
 --- Parameters:
 ---  * `mode` - The name of the current mode
 ---  * `shortcut` - A shortcut object containing the keybindings and event handler for the entity
+---  * `workflow` - The list of events that compose the current workflow
 ---
 --- Returns:
 ---  * A boolean denoting to whether enable or disable automatic mode exit after the action has been dispatched
-function Entity:dispatchAction(mode, shortcut)
+function Entity:dispatchAction(mode, shortcut, workflow)
     local flags = shortcut.flags
     local keyName = shortcut.keyName
     local eventHandler = self.getEventHandler(self.shortcuts, flags, keyName)
@@ -287,7 +288,7 @@ function Entity:dispatchAction(mode, shortcut)
     if eventHandler then
         local behaviorFunc = self.behaviors[mode] or self.behaviors.default
 
-        return behaviorFunc(self, eventHandler, flags, keyName)
+        return behaviorFunc(self, eventHandler, flags, keyName, workflow)
     else
         return self.autoExitMode
     end
diff --git a/src/init.lua b/src/init.lua
index 0f9b9c1..7f069e7 100644
--- a/src/init.lua
+++ b/src/init.lua
@@ -431,9 +431,18 @@ Ki.statusDisplay = nil
 
 -- A table that stores the workflow history.
 Ki.history = {
+    workflow = {},
     action = {},
 }
 
+function Ki.history:recordEvent(mode, keyName, flags)
+    table.insert(self.workflow, {
+        mode = mode,
+        flags = flags,
+        keyName = keyName,
+    })
+end
+
 function Ki._renderHotkeyText(modifiers, keyName)
     local modKeyText = ""
     local modNames = {
@@ -470,6 +479,7 @@ function Ki:_createFsmCallbacks()
         self.statusDisplay:show(stateMachine.current, parenthetical)
 
         if nextState == "desktop" then
+            self.history.workflow = {}
             self.history.action = {}
         end
     end
@@ -512,8 +522,10 @@ function Ki:_handleKeyDown(event)
 
     -- Avoid propagating existing handler or non-existent handler in a non-normal mode
     if handler then
+        Ki.history:recordEvent(mode, keyName, flags)
+
         if type(handler) == "table" and handler.dispatchAction then
-            local shouldAutoExit = handler:dispatchAction(mode, Ki.history.action)
+            local shouldAutoExit = handler:dispatchAction(mode, Ki.history.action, Ki.history.workflow)
 
             if shouldAutoExit then
                 self.state:exitMode()

From d52d051305edf33ad84df4cb5eb3e1ec4bf44dd0 Mon Sep 17 00:00:00 2001
From: Andrew Kwon <andrewshky@gmail.com>
Date: Sun, 3 Feb 2019 15:47:59 -0800
Subject: [PATCH 2/5] Add custom behavior in file mode to select files

---
 docs/html/Entity.html   |  1 +
 docs/markdown/Entity.md |  2 +-
 src/file.lua            | 25 +++++++++++++++++++++++--
 src/init.lua            |  6 ++++++
 4 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/docs/html/Entity.html b/docs/html/Entity.html
index a611426..d14e551 100644
--- a/docs/html/Entity.html
+++ b/docs/html/Entity.html
@@ -109,6 +109,7 @@ <h5><a href="#dispatchAction">dispatchAction</a></h5>
 <ul>
 <li><code>mode</code> - The name of the current mode</li>
 <li><code>shortcut</code> - A shortcut object containing the keybindings and event handler for the entity</li>
+<li><code>workflow</code> - The list of events that compose the current workflow</li>
 </ul>
 <p>Returns:</p>
 <ul>
diff --git a/docs/markdown/Entity.md b/docs/markdown/Entity.md
index 637c7c4..0608e22 100644
--- a/docs/markdown/Entity.md
+++ b/docs/markdown/Entity.md
@@ -42,7 +42,7 @@ Entity class that represents some generic automatable desktop entity
 | **Signature**                               | `Entity:dispatchAction(mode, shortcut) -> boolean`                                                                    |
 | **Type**                                    | Method                                                                     |
 | **Description**                             | Dispatch an action from a shortcut within the context of the given mode                                                                     |
-| **Parameters**                              | <ul><li>`mode` - The name of the current mode</li><li>`shortcut` - A shortcut object containing the keybindings and event handler for the entity</li></ul> |
+| **Parameters**                              | <ul><li>`mode` - The name of the current mode</li><li>`shortcut` - A shortcut object containing the keybindings and event handler for the entity</li><li>`workflow` - The list of events that compose the current workflow</li></ul> |
 | **Returns**                                 | <ul><li>A boolean denoting to whether enable or disable automatic mode exit after the action has been dispatched</li></ul>          |
 
 | [getEventHandler](#getEventHandler)         |                                                                                     |
diff --git a/src/file.lua b/src/file.lua
index 5abdde0..854392a 100644
--- a/src/file.lua
+++ b/src/file.lua
@@ -33,6 +33,20 @@ File.behaviors = Entity.behaviors + {
         eventHandler(self.path)
         return true
     end,
+    file = function(self, eventHandler, _, _, workflow)
+        local shouldNavigate = false
+
+        for _, event in pairs(workflow) do
+            if event.mode == "select" then
+                shouldNavigate = true
+                break
+            end
+        end
+
+        eventHandler(self.path, shouldNavigate)
+
+        return true
+    end,
 }
 
 --- File:initialize(path, shortcuts)
@@ -57,17 +71,24 @@ function File:initialize(path, shortcuts)
     local absolutePath = hs.fs.pathToAbsolute(path)
     local attributes = hs.fs.attributes(absolutePath) or {}
     local isDirectory = attributes.mode == "directory"
+    local openFileInFolder = self:createEvent(path, function(target) self.open(target) end)
 
     local actions = {
-        open = self.open,
         copy = function(target) self:copy(target) end,
         move = function(target) self:move(target) end,
         showCheatsheet = function() self.cheatsheet:show() end,
-        openFileInFolder = self:createEvent(path, function(target) self.open(target) end),
+        openFileInFolder = openFileInFolder,
         openFileInFolderWith = self:createEvent(path, function(target) self:openWith(target) end),
         showInfoForFileInFolder = self:createEvent(path, function(target) self:openInfoWindow(target) end),
         quickLookFileInFolder = self:createEvent(path, function(target) hs.execute("qlmanage -p "..target) end),
         deleteFileInFolder = self:createEvent(path, function(target) self:moveToTrash(target) end),
+        open = function(target, shouldNavigate)
+            if shouldNavigate then
+                return openFileInFolder(target)
+            end
+
+            return self.open(target)
+        end,
     }
     local commonShortcuts = {
         { nil, nil, actions.open, { path, "Activate/Focus" } },
diff --git a/src/init.lua b/src/init.lua
index 7f069e7..a5463ed 100644
--- a/src/init.lua
+++ b/src/init.lua
@@ -334,6 +334,11 @@ Ki.defaultTransitionEvents = {
             function() Ki.state:exitMode() end,
             { "Select Mode", "Exit to Normal Mode" },
         },
+        {
+            {"cmd"}, "f",
+            function() Ki.state:enterFileMode() end,
+            { "Select Mode", "Transition to File Mode" },
+        },
     },
     url = {
         {
@@ -378,6 +383,7 @@ Ki._defaultStateEvents = {
     { name = "enterSelectMode", from = "normal", to = "select" },
     { name = "enterFileMode", from = "normal", to = "file" },
     { name = "enterFileMode", from = "entity", to = "file" },
+    { name = "enterFileMode", from = "select", to = "file" },
     { name = "enterSelectMode", from = "file", to = "select" },
     { name = "enterVolumeControlMode", from = "normal", to = "volume" },
     { name = "enterBrightnessControlMode", from = "normal", to = "brightness" },

From 69edaf8e631c3a0d0c048f1ab0ab1ab820ef4420 Mon Sep 17 00:00:00 2001
From: Andrew Kwon <andrewshky@gmail.com>
Date: Sun, 3 Feb 2019 16:34:02 -0800
Subject: [PATCH 3/5] Add select->entity transition for consistency

---
 spec/application.spec.lua | 38 +++++++++++++++++
 src/application.lua       | 89 ++++++++++++++++++++++++++-------------
 src/init.lua              |  6 +++
 3 files changed, 103 insertions(+), 30 deletions(-)

diff --git a/spec/application.spec.lua b/spec/application.spec.lua
index 352085b..8a2c0e1 100644
--- a/spec/application.spec.lua
+++ b/spec/application.spec.lua
@@ -592,6 +592,43 @@ local function selectBehaviorTests()
     end
 end
 
+local function entityBehaviorTests()
+    local behaviorTests = {
+        {
+            name = "returns assigned auto-exit value if application has name",
+            applicationName = "",
+            autoExitMode = false,
+            args = { spy.new(function() end), nil, nil, {} },
+            eventHandlerCallCount = 0,
+            expectedResult = false,
+        },
+    }
+
+    -- Run `entity` mode behavior method tests
+    for _, test in pairs(behaviorTests) do
+        it(test.name, function()
+            local eventHandlerSpy = test.args[1]
+            local application = require("application")
+
+            application.name = test.applicationName
+            application.autoExitMode = test.autoExitMode
+            application.getSelectionItems = function()
+                return test.selectionItems
+            end
+            application.getApplication = function()
+                return #test.applicationName > 0 and {} or nil
+            end
+
+            assert.are.same(type(application.behaviors.entity), "function")
+
+            local result = application.behaviors.entity(application, table.unpack(test.args))
+
+            assert.are.same(test.expectedResult, result)
+            assert.spy(eventHandlerSpy).was.called(test.eventHandlerCallCount)
+        end)
+    end
+end
+
 describe("application.lua (#application)", function()
     local printFunc = _G.print
 
@@ -624,4 +661,5 @@ describe("application.lua (#application)", function()
     describe("`toggleFullScreen` method", toggleFullScreenTests)
     describe("`default` behavior function", defaultBehaviorTests)
     describe("`select` behavior function", selectBehaviorTests)
+    describe("`entity` behavior function", entityBehaviorTests)
 end)
diff --git a/src/application.lua b/src/application.lua
index c697023..a799a4e 100644
--- a/src/application.lua
+++ b/src/application.lua
@@ -23,48 +23,77 @@ end
 
 local Entity = _G.requirePackage("Entity", true)
 local Application = Entity:subclass("Application")
+local ApplicationBehaviors = {}
 
---- Application.behaviors
---- Variable
---- Application [behaviors](Entity.html#behaviors) defined to invoke event handlers with `hs.application`.
-Application.behaviors = Entity.behaviors + {
-    default = function(self, eventHandler)
-        local app = self.name and self:getApplication() or nil
+-- Default application behavior function
+function ApplicationBehaviors.default(self, eventHandler)
+    local app = self.name and self:getApplication() or nil
 
-        if not app then
-            return self.autoExitMode
-        end
+    if not app then
+        return self.autoExitMode
+    end
 
-        local autoFocus, autoExit = eventHandler(app)
+    local autoFocus, autoExit = eventHandler(app)
 
-        if app and autoFocus == true then
-            self.focus(app)
-        end
+    if app and autoFocus == true then
+        self.focus(app)
+    end
 
-        return autoExit == nil and self.autoExitMode or autoExit
-    end,
-    select = function(self, eventHandler)
-        local app = self.name and self:getApplication() or nil
+    return autoExit == nil and self.autoExitMode or autoExit
+end
 
-        if not app then
-            return self.autoExitMode
-        end
+-- Application behavior function for select mode
+function ApplicationBehaviors.select(self, eventHandler)
+    local app = self.name and self:getApplication() or nil
 
-        local choices = self:getSelectionItems()
+    if not app then
+        return self.autoExitMode
+    end
 
-        if choices and #choices > 0 then
-            local function onSelection(choice)
-                if choice then
-                    eventHandler(app, choice)
-                end
+    local choices = self:getSelectionItems()
+
+    if choices and #choices > 0 then
+        local function onSelection(choice)
+            if choice then
+                eventHandler(app, choice)
             end
+        end
+
+        self.showSelectionModal(choices, onSelection)
+    end
 
-            self.showSelectionModal(choices, onSelection)
+    return true
+end
+
+-- Application behavior function for entity mode
+function ApplicationBehaviors.entity(self, eventHandler, _, _, workflow)
+    local shouldSelect = false
+    local app = self.name and self:getApplication() or nil
+
+    if not app then
+        return self.autoExitMode
+    end
+
+    for _, event in pairs(workflow) do
+        if event.mode == "select" then
+            shouldSelect = true
+            break
         end
+    end
 
-        return true
-    end,
-}
+    if shouldSelect then
+        return ApplicationBehaviors.select(self, eventHandler, _, _, workflow)
+    end
+
+    local _, autoExit = eventHandler(app, shouldSelect)
+
+    return autoExit == nil and self.autoExitMode or autoExit
+end
+
+--- Application.behaviors
+--- Variable
+--- Application [behaviors](Entity.html#behaviors) defined to invoke event handlers with `hs.application`.
+Application.behaviors = Entity.behaviors + ApplicationBehaviors
 
 --- Application:getSelectionItems()
 --- Method
diff --git a/src/init.lua b/src/init.lua
index a5463ed..7397e77 100644
--- a/src/init.lua
+++ b/src/init.lua
@@ -334,6 +334,11 @@ Ki.defaultTransitionEvents = {
             function() Ki.state:exitMode() end,
             { "Select Mode", "Exit to Normal Mode" },
         },
+        {
+            {"cmd"}, "e",
+            function() Ki.state:enterEntityMode() end,
+            { "Select Mode", "Transition to Entity Mode" },
+        },
         {
             {"cmd"}, "f",
             function() Ki.state:enterFileMode() end,
@@ -378,6 +383,7 @@ Ki._defaultStateEvents = {
     { name = "enterNormalMode", from = "desktop", to = "normal" },
     { name = "enterEntityMode", from = "normal", to = "entity" },
     { name = "enterEntityMode", from = "action", to = "entity" },
+    { name = "enterEntityMode", from = "select", to = "entity" },
     { name = "enterActionMode", from = "normal", to = "action" },
     { name = "enterSelectMode", from = "entity", to = "select" },
     { name = "enterSelectMode", from = "normal", to = "select" },

From ed6120ec20a91802a9ab56d046345329a48c09c0 Mon Sep 17 00:00:00 2001
From: Andrew Kwon <andrewshky@gmail.com>
Date: Fri, 8 Feb 2019 20:50:40 -0800
Subject: [PATCH 4/5] Add Smart Folder class & update file defaults

- Implement Recents folder with Smart Folder class
- Add <C-u> and <C-d> selection modal shortcuts
- Fix iCloud Drive event handler
---
 docs/html/Entity.html        |   2 +
 docs/html/File.html          |  40 +++-
 docs/html/SmartFolder.html   | 267 ++++++++++++++++++++++++
 docs/html/index.html         |   7 +-
 docs/markdown/File.md        |  13 +-
 docs/markdown/SmartFolder.md |  85 ++++++++
 docs/markdown/index.md       |   3 +-
 spec/file.spec.lua           |  33 ++-
 spec/init.spec.lua           |  10 +-
 spec/smart-folder.spec.lua   | 391 +++++++++++++++++++++++++++++++++++
 src/defaults.lua             |   9 +-
 src/entity.lua               |   4 +
 src/file.lua                 |  58 ++++--
 src/smart-folder.lua         | 222 ++++++++++++++++++++
 14 files changed, 1109 insertions(+), 35 deletions(-)
 create mode 100644 docs/html/SmartFolder.html
 create mode 100644 docs/markdown/SmartFolder.md
 create mode 100644 spec/smart-folder.spec.lua
 create mode 100644 src/smart-folder.lua

diff --git a/docs/html/Entity.html b/docs/html/Entity.html
index d14e551..32d5266 100644
--- a/docs/html/Entity.html
+++ b/docs/html/Entity.html
@@ -84,6 +84,8 @@ <h5><a href="#selectionModalShortcuts">selectionModalShortcuts</a></h5>
 <ul>
 <li><kbd>^k</kbd> to navigate up an item</li>
 <li><kbd>^j</kbd> to navigate down an item</li>
+<li><kbd>^u</kbd> to navigate a page of rows up</li>
+<li><kbd>^d</kbd> to navigate a page of rows down</li>
 </ul>
 </td>
               </tr>
diff --git a/docs/html/File.html b/docs/html/File.html
index 396dd5e..86102b6 100644
--- a/docs/html/File.html
+++ b/docs/html/File.html
@@ -15,7 +15,7 @@
   <body>
     <header>
       <h1><a href="./index.html">docs</a> &raquo; File</h1>
-      <p>File class that subclasses <a href="Entity.html">Entity</a> to represent some directory or file</p>
+      <p>File class that subclasses <a href="Entity.html">Entity</a> to represent some directory or file to be automated</p>
 
       </header>
       <h3>API Overview</h3>
@@ -28,6 +28,7 @@ <h3>API Overview</h3>
           <ul>
             <li><a href="#copy">copy</a></li>
             <li><a href="#createEvent">createEvent</a></li>
+            <li><a href="#createFileChoices">createFileChoices</a></li>
             <li><a href="#getFileIcon">getFileIcon</a></li>
             <li><a href="#initialize">initialize</a></li>
             <li><a href="#move">move</a></li>
@@ -112,6 +113,41 @@ <h5><a href="#createEvent">createEvent</a></h5>
 <ul>
 <li>An event handler function</li>
 </ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="createFileChoices">
+            <a name="//apple_ref/cpp/Method/createFileChoices" class="dashAnchor"></a>
+            <h5><a href="#createFileChoices">createFileChoices</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>File.createFileChoices(fileListIterator, createText, createSubText) -&gt; choice object list</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Creates a list of choice objects each representing the file walked with the provided iterator</p>
+<p>Parameters:</p>
+<ul>
+<li><code>fileListIterator</code> - an iterator to walk a list of file paths, i.e. <code>s:gmatch(pattern)</code></li>
+<li><code>createText</code> - an optional function that takes in a single <code>path</code> argument to return a formatted string to assign to the <code>text</code> field in each file choice object</li>
+<li><code>createSubText</code> - an optional function that takes in a single <code>path</code> argument to return a formatted string to assign to the <code>subText</code> field in each file choice object</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li><code>choices</code> - A list of choice objects each containing the following fields:<ul>
+<li><code>text</code> - The primary chooser text string</li>
+<li><code>subText</code> - The chooser subtext string</li>
+<li><code>fileName</code> - The name of the file</li>
+<li><code>path</code> - The path of the file</li>
+</ul>
+</li>
+</ul>
 </td>
               </tr>
             </table>
@@ -130,7 +166,7 @@ <h5><a href="#getFileIcon">getFileIcon</a></h5>
               </tr>
               <tr>
                 <th>Description</th>
-                <td><p>Retrieves an icon image for the given file path or returns nil if not found</p>
+                <td><p>Retrieves an icon image for the given file path or returns <code>nil</code> if not found</p>
 <p>Parameters:</p>
 <ul>
 <li><code>path</code> - The path of a file</li>
diff --git a/docs/html/SmartFolder.html b/docs/html/SmartFolder.html
new file mode 100644
index 0000000..13aa140
--- /dev/null
+++ b/docs/html/SmartFolder.html
@@ -0,0 +1,267 @@
+<html>
+    <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Ki docs: SmartFolder</title>
+    <style type="text/css">
+      a { text-decoration: none; }
+      a:hover { text-decoration: underline; }
+      th { background-color: #DDDDDD; vertical-align: top; padding: 3px; }
+      td { width: 100%; background-color: #EEEEEE; vertical-align: top; padding: 3px; }
+      table { width: 100% ; border: 1px solid #0; text-align: left; }
+      section > table table td { width: 0; }
+    </style>
+    <link rel="stylesheet" href="docs.css" type="text/css" media="screen" />
+  </head>
+  <body>
+    <header>
+      <h1><a href="./index.html">docs</a> &raquo; SmartFolder</h1>
+      <p>SmartFolder class that subclasses <a href="File.html">File</a> to represent a <a href="https://support.apple.com/kb/PH25589">smart folder</a> to be automated</p>
+
+      </header>
+      <h3>API Overview</h3>
+      <ul>
+        <li>Methods - API calls which can only be made on an object returned by a constructor</li>
+          <ul>
+            <li><a href="#copy">copy</a></li>
+            <li><a href="#initialize">initialize</a></li>
+            <li><a href="#move">move</a></li>
+            <li><a href="#moveToTrash">moveToTrash</a></li>
+            <li><a href="#openFile">openFile</a></li>
+            <li><a href="#openFileWith">openFileWith</a></li>
+            <li><a href="#openInfoWindow">openInfoWindow</a></li>
+            <li><a href="#showFileSearchSelectionModal">showFileSearchSelectionModal</a></li>
+          </ul>
+      </ul>
+      <h3>API Documentation</h3>
+        <h4 class="documentation-section">Methods</h4>
+          <section id="copy">
+            <a name="//apple_ref/cpp/Method/copy" class="dashAnchor"></a>
+            <h5><a href="#copy">copy</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:copy(path)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Copies a file in the smart folder search results to different folder</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="initialize">
+            <a name="//apple_ref/cpp/Method/initialize" class="dashAnchor"></a>
+            <h5><a href="#initialize">initialize</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:initialize(path, shortcuts)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Initializes a new smart folder entity instance with its search criteria file and custom shortcuts. By default, a cheatsheet and default shortcuts are initialized.</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+<li><code>shortcuts</code> - The list of shortcuts containing keybindings and actions for the smart folder entity</li>
+</ul>
+<p>Each <code>shortcut</code> item should be a list with items at the following indices:</p>
+<ul>
+<li><code>1</code> - An optional table containing zero or more of the following keyboard modifiers: <code>"cmd"</code>, <code>"alt"</code>, <code>"shift"</code>, <code>"ctrl"</code>, <code>"fn"</code></li>
+<li><code>2</code> - The name of a keyboard key. String representations of keys can be found in <a href="https://www.hammerspoon.org/docs/hs.keycodes.html#map"><code>hs.keycodes.map</code></a>.</li>
+<li><code>3</code> - The event handler that defines the action for when the shortcut is triggered</li>
+<li><code>4</code> - A table containing the metadata for the shortcut, also a list with items at the following indices:<ul>
+<li><code>1</code> - The category name of the shortcut</li>
+<li><code>2</code> - A description of what the shortcut does</li>
+</ul>
+</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="move">
+            <a name="//apple_ref/cpp/Method/move" class="dashAnchor"></a>
+            <h5><a href="#move">move</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:move(path)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Moves a selected file in the smart folder to a different folder</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="moveToTrash">
+            <a name="//apple_ref/cpp/Method/moveToTrash" class="dashAnchor"></a>
+            <h5><a href="#moveToTrash">moveToTrash</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:moveToTrash(path)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Moves a selected file in the smart folder search results to the Trash</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="openFile">
+            <a name="//apple_ref/cpp/Method/openFile" class="dashAnchor"></a>
+            <h5><a href="#openFile">openFile</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:openFile(path)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Open a file from the smart folder search results</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="openFileWith">
+            <a name="//apple_ref/cpp/Method/openFileWith" class="dashAnchor"></a>
+            <h5><a href="#openFileWith">openFileWith</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:openFileWith(path)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Open a file selected from the smart folder search results with a specific application</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="openInfoWindow">
+            <a name="//apple_ref/cpp/Method/openInfoWindow" class="dashAnchor"></a>
+            <h5><a href="#openInfoWindow">openInfoWindow</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:openInfoWindow(path)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Opens a Finder information window for the file selected from the smart folder search results</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="showFileSearchSelectionModal">
+            <a name="//apple_ref/cpp/Method/showFileSearchSelectionModal" class="dashAnchor"></a>
+            <h5><a href="#showFileSearchSelectionModal">showFileSearchSelectionModal</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>SmartFolder:showFileSearchSelectionModal(path, callback)</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Shows a selection modal with smart folder search result choices</p>
+<p>Parameters:</p>
+<ul>
+<li><code>path</code> - The path of the smart folder (<code>.savedSearch</code> file)</li>
+<li><code>callback</code> - The callback function invoked on a file choice selection with a choice object created from <a href="File.html#createFileChoices"><code>File.createFileChoices</code></a></li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>None</li>
+</ul>
+</td>
+              </tr>
+            </table>
+          </section>
+  </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/index.html b/docs/html/index.html
index 9c9438e..f998f23 100644
--- a/docs/html/index.html
+++ b/docs/html/index.html
@@ -69,12 +69,17 @@ <h3>API documentation</h3>
             </tr>
             <tr>
                 <th><a href="File.html">File</a></th>
-                <td><p>File class that subclasses <a href="Entity.html">Entity</a> to represent some directory or file</p>
+                <td><p>File class that subclasses <a href="Entity.html">Entity</a> to represent some directory or file to be automated</p>
 </td>
             </tr>
             <tr>
                 <th><a href="Ki.html">Ki</a></th>
                 <td><p><strong>Expressive modal macOS automation, inspired by vi</strong></p>
+</td>
+            </tr>
+            <tr>
+                <th><a href="SmartFolder.html">SmartFolder</a></th>
+                <td><p>SmartFolder class that subclasses <a href="File.html">File</a> to represent a <a href="https://support.apple.com/kb/PH25589">smart folder</a> to be automated</p>
 </td>
             </tr>
             <tr>
diff --git a/docs/markdown/File.md b/docs/markdown/File.md
index 70ea2bc..a4b8fd9 100644
--- a/docs/markdown/File.md
+++ b/docs/markdown/File.md
@@ -1,7 +1,7 @@
 # [docs](index.md) » File
 ---
 
-File class that subclasses [Entity](Entity.html) to represent some directory or file
+File class that subclasses [Entity](Entity.html) to represent some directory or file to be automated
 
 
 ## API Overview
@@ -10,6 +10,7 @@ File class that subclasses [Entity](Entity.html) to represent some directory or
 * Methods - API calls which can only be made on an object returned by a constructor
  * [copy](#copy)
  * [createEvent](#createEvent)
+ * [createFileChoices](#createFileChoices)
  * [getFileIcon](#getFileIcon)
  * [initialize](#initialize)
  * [move](#move)
@@ -49,11 +50,19 @@ File class that subclasses [Entity](Entity.html) to represent some directory or
 | **Parameters**                              | <ul><li>`path` - The path of a file</li></ul> |
 | **Returns**                                 | <ul><li> An event handler function</li></ul>          |
 
+| [createFileChoices](#createFileChoices)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `File.createFileChoices(fileListIterator, createText, createSubText) -> choice object list`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Creates a list of choice objects each representing the file walked with the provided iterator                                                                     |
+| **Parameters**                              | <ul><li>`fileListIterator` - an iterator to walk a list of file paths, i.e. `s:gmatch(pattern)`</li><li>`createText` - an optional function that takes in a single `path` argument to return a formatted string to assign to the `text` field in each file choice object</li><li>`createSubText` - an optional function that takes in a single `path` argument to return a formatted string to assign to the `subText` field in each file choice object</li></ul> |
+| **Returns**                                 | <ul><li> `choices` - A list of choice objects each containing the following fields:</li><li>   `text` - The primary chooser text string</li><li>   `subText` - The chooser subtext string</li><li>   `fileName` - The name of the file</li><li>   `path` - The path of the file</li></ul>          |
+
 | [getFileIcon](#getFileIcon)         |                                                                                     |
 | --------------------------------------------|-------------------------------------------------------------------------------------|
 | **Signature**                               | `File:getFileIcon(path) -> [`hs.image`](http://www.hammerspoon.org/docs/hs.image.html)`                                                                    |
 | **Type**                                    | Method                                                                     |
-| **Description**                             | Retrieves an icon image for the given file path or returns nil if not found                                                                     |
+| **Description**                             | Retrieves an icon image for the given file path or returns `nil` if not found                                                                     |
 | **Parameters**                              | <ul><li>`path` - The path of a file</li></ul> |
 | **Returns**                                 | <ul><li> The file icon [`hs.image`](http://www.hammerspoon.org/docs/hs.image.html) object</li></ul>          |
 
diff --git a/docs/markdown/SmartFolder.md b/docs/markdown/SmartFolder.md
new file mode 100644
index 0000000..26ff6e8
--- /dev/null
+++ b/docs/markdown/SmartFolder.md
@@ -0,0 +1,85 @@
+# [docs](index.md) » SmartFolder
+---
+
+SmartFolder class that subclasses [File](File.html) to represent a [smart folder](https://support.apple.com/kb/PH25589) to be automated
+
+
+## API Overview
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [copy](#copy)
+ * [initialize](#initialize)
+ * [move](#move)
+ * [moveToTrash](#moveToTrash)
+ * [openFile](#openFile)
+ * [openFileWith](#openFileWith)
+ * [openInfoWindow](#openInfoWindow)
+ * [showFileSearchSelectionModal](#showFileSearchSelectionModal)
+
+## API Documentation
+
+### Methods
+
+| [copy](#copy)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:copy(path)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Copies a file in the smart folder search results to different folder                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [initialize](#initialize)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:initialize(path, shortcuts)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Initializes a new smart folder entity instance with its search criteria file and custom shortcuts. By default, a cheatsheet and default shortcuts are initialized.                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li><li>`shortcuts` - The list of shortcuts containing keybindings and actions for the smart folder entity</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [move](#move)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:move(path)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Moves a selected file in the smart folder to a different folder                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [moveToTrash](#moveToTrash)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:moveToTrash(path)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Moves a selected file in the smart folder search results to the Trash                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [openFile](#openFile)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:openFile(path)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Open a file from the smart folder search results                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [openFileWith](#openFileWith)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:openFileWith(path)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Open a file selected from the smart folder search results with a specific application                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [openInfoWindow](#openInfoWindow)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:openInfoWindow(path)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Opens a Finder information window for the file selected from the smart folder search results                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
+| [showFileSearchSelectionModal](#showFileSearchSelectionModal)         |                                                                                     |
+| --------------------------------------------|-------------------------------------------------------------------------------------|
+| **Signature**                               | `SmartFolder:showFileSearchSelectionModal(path, callback)`                                                                    |
+| **Type**                                    | Method                                                                     |
+| **Description**                             | Shows a selection modal with smart folder search result choices                                                                     |
+| **Parameters**                              | <ul><li>`path` - The path of the smart folder (`.savedSearch` file)</li><li>`callback` - The callback function invoked on a file choice selection with a choice object created from [`File.createFileChoices`](File.html#createFileChoices)</li></ul> |
+| **Returns**                                 | <ul><li>None</li></ul>          |
+
diff --git a/docs/markdown/index.md b/docs/markdown/index.md
index 96214d1..bb66932 100644
--- a/docs/markdown/index.md
+++ b/docs/markdown/index.md
@@ -16,6 +16,7 @@
 | [Cheatsheet](Cheatsheet.md)                          | Cheatsheet modal used to display keyboard shortcuts     |
 | [Defaults](Defaults.md)                          | Definitions of default events and entities     |
 | [Entity](Entity.md)                          | Entity class that represents some generic automatable desktop entity     |
-| [File](File.md)                          | File class that subclasses [Entity](Entity.html) to represent some directory or file     |
+| [File](File.md)                          | File class that subclasses [Entity](Entity.html) to represent some directory or file to be automated     |
 | [Ki](Ki.md)                          | **Expressive modal macOS automation, inspired by vi**     |
+| [SmartFolder](SmartFolder.md)                          | SmartFolder class that subclasses [File](File.html) to represent a [smart folder](https://support.apple.com/kb/PH25589) to be automated     |
 | [StatusDisplay](StatusDisplay.md)                          | Small menubar text display     |
diff --git a/spec/file.spec.lua b/spec/file.spec.lua
index f538df1..7a7585c 100644
--- a/spec/file.spec.lua
+++ b/spec/file.spec.lua
@@ -36,10 +36,20 @@ end
 local function behaviorTests()
     local tests = {
         {
-            name = "calls event handler with file path and auto-exits mode",
+            name = "default behavior: calls event handler with file path and auto-exits mode",
             behavior = "default",
-            args = { function() end },
+            path = "test",
+            args = { spy.new(function() end) },
             expectedResult = true,
+            expectedEventHandlerArgs = { "test" },
+        },
+        {
+            name = "file mode behavior: calls event handler with file path and should navigate flag and auto-exits mode",
+            behavior = "file",
+            path = "test",
+            args = { spy.new(function() end), _, _, { { mode = "select" } } },
+            expectedResult = true,
+            expectedEventHandlerArgs = { "test", true },
         },
     }
 
@@ -47,8 +57,11 @@ local function behaviorTests()
     for _, test in pairs(tests) do
         it(test.name, function()
             local file = require("file")
+            file.path = test.path
+
             local result = file.behaviors[test.behavior](file, table.unpack(test.args))
 
+            assert.spy(test.args[1]).was.called_with(table.unpack(test.expectedEventHandlerArgs))
             assert.are.same(test.expectedResult, result)
         end)
     end
@@ -397,14 +410,16 @@ local function openWithTests()
             shellOutput = "/Applications/Test.app\n/Applications/Utilities/Test.app\n",
             expectedChoices = {
                 {
-                    text = "/Applications/Test.app",
+                    text = "Test.app",
                     subText = "/Applications/Test.app",
-                    applicationPath =  "/Applications/Test.app",
+                    fileName =  "Test.app",
+                    path =  "/Applications/Test.app",
                 },
                 {
-                    text = "/Applications/Utilities/Test.app",
+                    text = "Test.app",
                     subText = "/Applications/Utilities/Test.app",
-                    applicationPath =  "/Applications/Utilities/Test.app",
+                    fileName =  "Test.app",
+                    path =  "/Applications/Utilities/Test.app",
                 },
             },
         },
@@ -417,13 +432,15 @@ local function openWithTests()
                 {
                     text = "Test",
                     subText = "/Applications/Test.app",
-                    applicationPath =  "/Applications/Test.app",
+                    path =  "/Applications/Test.app",
+                    fileName =  "Test.app",
                     image = { test = true },
                 },
                 {
                     text = "Test",
                     subText = "/Applications/Utilities/Test.app",
-                    applicationPath =  "/Applications/Utilities/Test.app",
+                    path =  "/Applications/Utilities/Test.app",
+                    fileName =  "Test.app",
                     image = { test = true },
                 },
             },
diff --git a/spec/init.spec.lua b/spec/init.spec.lua
index e16b65f..c102b20 100644
--- a/spec/init.spec.lua
+++ b/spec/init.spec.lua
@@ -32,7 +32,7 @@ local function requirePackageMocker(mocks)
         end
 
         if isInternal then
-            return mock(dofile("src/"..name..".lua"))
+            return mocks[name] or mock(dofile("src/"..name..".lua"))
         else
             if name == "fsm" then
                 return mocks.fsm or mock(mockFsm)
@@ -376,7 +376,13 @@ describe("init.lua (#init)", function()
         -- Setup each test with a fake Hammerspoon environment and mocked external dependencies
         package.loaded.init = nil
         _G.hs = mock(hammerspoonMocker()())
-        _G.requirePackage = requirePackageMocker()
+        _G.requirePackage = requirePackageMocker({
+            defaults = {
+                create = function()
+                    return {}, {}
+                end,
+            },
+        })
     end)
 
     after_each(function ()
diff --git a/spec/smart-folder.spec.lua b/spec/smart-folder.spec.lua
new file mode 100644
index 0000000..9836373
--- /dev/null
+++ b/spec/smart-folder.spec.lua
@@ -0,0 +1,391 @@
+local say = require("say")
+local assertions = require("spec.assertions")
+local hammerspoonMocker = require("spec.mock-hammerspoon")
+
+assertions:init(say, assert)
+
+-- Generate `requirePackage` function to mock external dependencies
+local function requirePackageMocker(mocks)
+    mocks = mocks or {}
+
+    local defaultMocks = {
+        lustache = mocks.lustache or mock({
+            render = function() end
+        }),
+        middleclass = mocks.middleclass or mock(function()
+            return {
+                subclass = function()
+                    return {}
+                end
+            }
+        end),
+    }
+
+    for key, value in pairs(mocks) do
+        defaultMocks[key] = value
+    end
+
+    mocks = defaultMocks
+
+    return function(name, isInternal)
+        if isInternal then
+            return mocks[name] or mock(dofile("src/"..name..".lua"))
+        else
+            return mocks[name]
+        end
+    end
+end
+
+-- SmartFolder `initialize` method test suite
+local function initializeTests()
+    local tests = {
+        {
+            name = "creates a smart folder entity instance",
+            args = { "~/.savedSearch" },
+        },
+    }
+
+    -- Run `initialize` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local mockHs = hammerspoonMocker()
+            local SmartFolder = require("smart-folder")
+            local mockFs = {
+                pathToAbsolute = function() return test.args[1] end,
+            }
+
+            _G.hs = mock(mockHs({ fs = mockFs }))
+
+            SmartFolder.mergeShortcuts = function() end
+            SmartFolder:initialize(table.unpack(test.args))
+
+            assert.are.same(SmartFolder.path, test.args[1])
+        end)
+    end
+end
+
+-- SmartFolder `showFileSearchSelectionModal` method test suite
+local function showFileSearchSelectionModalTests()
+    local tests = {
+        {
+            name = "creates a smart folder entity instance",
+            args = { "~/.savedSearch" },
+            shellOutput  = "/test/path1\n/test/path2\n",
+            expectedChoices = {},
+        },
+    }
+
+    -- Run `showFileSearchSelectionModal` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local mockHs = hammerspoonMocker()
+            local SmartFolder = require("smart-folder")
+            local mockFs = {
+                pathToAbsolute = function() return test.args[1] end,
+            }
+
+            _G.hs = mock(mockHs({
+                fs = mockFs,
+                execute = function()
+                    return test.shellOutput
+                end,
+            }))
+
+            SmartFolder.createFileChoices = function()
+                return test.expectedChoices
+            end
+            SmartFolder.showSelectionModal = function(choices)
+                assert.are.same(choices, test.expectedChoices)
+            end
+
+            SmartFolder:showFileSearchSelectionModal(table.unpack(test.args))
+        end)
+    end
+end
+
+-- SmartFolder `openFile` method test suite
+local function openFileTests()
+    local tests = {
+        {
+            name = "does not open file without a selection",
+            args = { "~/.savedSearch" },
+            choice = nil,
+            opensFile = false,
+        },
+        {
+            name = "opens file with a path selection",
+            args = { "~/.savedSearch" },
+            choice = "/test/path",
+            opensFile = true,
+        },
+    }
+
+    -- Run `showFileSearchSelectionModal` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local SmartFolder = require("smart-folder")
+
+            SmartFolder.showFileSearchSelectionModal = function(_, _, callback)
+                return callback(test.choice)
+            end
+
+            SmartFolder:openFile(table.unpack(test.args))
+        end)
+    end
+end
+
+-- SmartFolder `copy` method test suite
+local function copyTests()
+    local tests = {
+        {
+            name = "copies from a source file to a destination folder",
+            args = { "~/.savedSearch" },
+            choice1 = "/test/source.txt",
+            choice2 = "/test/destination",
+            navigates = true,
+        },
+        {
+            name = "cancels copying if no selection is made",
+            args = { "~/.savedSearch" },
+            navigates = false,
+        },
+    }
+
+    -- Run `copy` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local mockHs = hammerspoonMocker()
+            local SmartFolder = require("smart-folder")
+            local mockFs = {
+                pathToAbsolute = function() return test.args[1] end,
+            }
+
+            _G.hs = mock(mockHs({ fs = mockFs }))
+
+            SmartFolder.showFileSearchSelectionModal = function(_, _, callback)
+                return callback(test.choice1 and { path = test.choice1 } or nil)
+            end
+            SmartFolder.navigate = spy.new(function(_, _, callback)
+                return callback(test.choice2)
+            end)
+            SmartFolder.triggerAfterConfirmation = function(_, callback)
+                return callback()
+            end
+            SmartFolder.runFileModeApplescript = function(_, viewModel)
+                assert.are.same(viewModel.filePath1, test.choice1)
+                assert.are.same(viewModel.filePath2, test.choice2)
+            end
+
+            SmartFolder:copy(table.unpack(test.args))
+
+            assert.spy(SmartFolder.navigate).was.called(test.navigates and 1 or 0)
+        end)
+    end
+end
+
+-- SmartFolder `moveToTrash` method test suite
+local function moveToTrashTests()
+    local tests = {
+        {
+            name = "does not open file without a selection",
+            args = { "~/.savedSearch" },
+            choice = nil,
+            movesToTrash = false,
+        },
+        {
+            name = "opens file with a path selection",
+            args = { "~/.savedSearch" },
+            choice = "/test/path",
+            movesToTrash = true,
+        },
+    }
+
+    -- Run `showFileSearchSelectionModal` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local moveToTrashSpy = spy.new(function() end);
+
+            _G.requirePackage = requirePackageMocker({
+                File = mock({
+                    subclass = function() return {} end,
+                    moveToTrash = moveToTrashSpy,
+                }),
+            })
+
+            local SmartFolder = require("smart-folder")
+
+            SmartFolder.showFileSearchSelectionModal = function(_, _, callback)
+                return callback(test.choice)
+            end
+
+            SmartFolder:moveToTrash(table.unpack(test.args))
+
+            assert.spy(moveToTrashSpy).was.called(test.movesToTrash and 1 or 0)
+        end)
+    end
+end
+
+-- SmartFolder `move` method test suite
+local function moveTests()
+    local tests = {
+        {
+            name = "moves a selected source file to a destination folder",
+            args = { "~/.savedSearch" },
+            choice1 = "/test/source.txt",
+            choice2 = "/test/destination",
+            navigates = true,
+        },
+        {
+            name = "cancels moving if no selection is made",
+            args = { "~/.savedSearch" },
+            navigates = false,
+        },
+    }
+
+    -- Run `move` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local mockHs = hammerspoonMocker()
+            local SmartFolder = require("smart-folder")
+            local mockFs = {
+                pathToAbsolute = function() return test.args[1] end,
+            }
+
+            _G.hs = mock(mockHs({ fs = mockFs }))
+
+            SmartFolder.showFileSearchSelectionModal = function(_, _, callback)
+                return callback(test.choice1 and { path = test.choice1 } or nil)
+            end
+            SmartFolder.navigate = spy.new(function(_, _, callback)
+                return callback(test.choice2)
+            end)
+            SmartFolder.triggerAfterConfirmation = function(_, callback)
+                return callback()
+            end
+            SmartFolder.runFileModeApplescript = function(_, viewModel)
+                assert.are.same(viewModel.filePath1, test.choice1)
+                assert.are.same(viewModel.filePath2, test.choice2)
+            end
+
+            SmartFolder:move(table.unpack(test.args))
+
+            assert.spy(SmartFolder.navigate).was.called(test.navigates and 1 or 0)
+        end)
+    end
+end
+
+-- SmartFolder `openFileWith` method test suite
+local function openFileWithTests()
+    local tests = {
+        {
+            name = "does not open file without a selection",
+            args = { "~/.savedSearch" },
+            choice = nil,
+            movesToTrash = false,
+        },
+        {
+            name = "opens file with a path selection",
+            args = { "~/.savedSearch" },
+            choice = "/test/path",
+            movesToTrash = true,
+        },
+    }
+
+    -- Run `showFileSearchSelectionModal` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local openFileWithSpy = spy.new(function() end);
+
+            _G.requirePackage = requirePackageMocker({
+                File = mock({
+                    subclass = function() return {} end,
+                    openWith = openFileWithSpy,
+                }),
+            })
+
+            local SmartFolder = require("smart-folder")
+
+            SmartFolder.showFileSearchSelectionModal = function(_, _, callback)
+                return callback(test.choice)
+            end
+
+            SmartFolder:openFileWith(table.unpack(test.args))
+
+            assert.spy(openFileWithSpy).was.called(test.movesToTrash and 1 or 0)
+        end)
+    end
+end
+
+-- SmartFolder `openInfoWindow` method test suite
+local function openInfoWindowTests()
+    local tests = {
+        {
+            name = "does not open file without a selection",
+            args = { "~/.savedSearch" },
+            choice = nil,
+            movesToTrash = false,
+        },
+        {
+            name = "opens file with a path selection",
+            args = { "~/.savedSearch" },
+            choice = "/test/path",
+            movesToTrash = true,
+        },
+    }
+
+    -- Run `showFileSearchSelectionModal` method tests
+    for _, test in pairs(tests) do
+        it(test.name, function()
+            local openInfoWindowSpy = spy.new(function() end);
+
+            _G.requirePackage = requirePackageMocker({
+                File = mock({
+                    subclass = function() return {} end,
+                    openInfoWindow = openInfoWindowSpy,
+                }),
+            })
+
+            local SmartFolder = require("smart-folder")
+
+            SmartFolder.showFileSearchSelectionModal = function(_, _, callback)
+                return callback(test.choice)
+            end
+
+            SmartFolder:openInfoWindow(table.unpack(test.args))
+
+            assert.spy(openInfoWindowSpy).was.called(test.movesToTrash and 1 or 0)
+        end)
+    end
+end
+
+describe("smart-folder.lua (#smartfolder)", function()
+    -- Set globals
+    _G.spoonPath = ""
+    _G.SHORTCUT_MODKEY_INDEX = 1
+    _G.SHORTCUT_HOTKEY_INDEX = 2
+    _G.SHORTCUT_EVENT_HANDLER_INDEX = 3
+    _G.SHORTCUT_METADATA_INDEX = 4
+
+    before_each(function()
+        -- Setup each test with a fake Hammerspoon environment and mocked external dependencies
+        package.loaded["smart-folder"] = nil
+        _G.hs = mock(hammerspoonMocker()())
+        _G.requirePackage = requirePackageMocker({
+            File = mock({ subclass = function() return {} end }),
+        })
+    end)
+
+    after_each(function()
+        _G.hs = nil
+        _G.requirePackage = nil
+    end)
+
+    describe("`initialize` method", initializeTests)
+    describe("`showFileSearchSelectionModal` method", showFileSearchSelectionModalTests)
+    describe("`openFile` method", openFileTests)
+    describe("`copy` method", copyTests)
+    describe("`moveToTrash` method", moveToTrashTests)
+    describe("`move` method", moveTests)
+    describe("`openFileWith` method", openFileWithTests)
+    describe("`openInfoWindow` method", openInfoWindowTests)
+end)
diff --git a/src/defaults.lua b/src/defaults.lua
index f407e85..08b97a7 100644
--- a/src/defaults.lua
+++ b/src/defaults.lua
@@ -23,6 +23,7 @@ if not _G.requirePackage then
 end
 
 local File = _G.requirePackage("file", true)
+local SmartFolder = _G.requirePackage("smart-folder", true)
 
 local entities = {
     ActivityMonitor = _G.requirePackage("entities/activity-monitor", true),
@@ -75,6 +76,10 @@ function Defaults.createFileEvents()
         end
     end
 
+    local recentsSavedSearchPath =
+        "/System/Library/CoreServices/Finder.app/Contents/Resources/MyLibraries/myDocuments.cannedSearch/Resources/search.savedSearch"
+    local Recents = SmartFolder:new(recentsSavedSearchPath)
+
     local fileEvents = {
         { nil, "a", File:new("/Applications"), { "Files", "Applications" } },
         { nil, "d", File:new("~/Downloads"), { "Files", "Downloads" } },
@@ -84,9 +89,9 @@ function Defaults.createFileEvents()
         { nil, "t", File:new("~/.Trash"), { "Files", "Trash" } },
         { { "cmd" }, "a", openFinderAppEvent("Airdrop"), { "Files", "Airdrop" } },
         { { "cmd" }, "c", openFinderAppEvent("Computer"), { "Files", "Computer" } },
-        { { "cmd" }, "i", openFinderAppEvent("iCloud Drive"), { "Files", "iCloud Drive" } },
+        { { "cmd" }, "i", openFinderAppEvent("iCloud\\ Drive"), { "Files", "iCloud Drive" } },
         { { "cmd" }, "n", openFinderAppEvent("Network"), { "Files", "Network" } },
-        { { "cmd" }, "r", openFinderAppEvent("Recents"), { "Files", "Recents" } },
+        { { "cmd" }, "r", Recents, { "Files", "Recents" } },
         { { "shift" }, "a", openFinderAppEvent("All My Files"), { "Files", "All My Files" } },
         { { "shift" }, "d", File:new("~/Desktop"), { "Files", "Desktop" } },
         { { "cmd", "shift" }, "d", File:new("~/Documents"), { "Files", "Documents" } },
diff --git a/src/entity.lua b/src/entity.lua
index 0ac77a2..5476580 100644
--- a/src/entity.lua
+++ b/src/entity.lua
@@ -198,9 +198,13 @@ end
 --- A list of shortcuts that can be used when the selection modal is visible. The following shortcuts are available by default:
 ---  * <kbd>^k</kbd> to navigate up an item
 ---  * <kbd>^j</kbd> to navigate down an item
+---  * <kbd>^u</kbd> to navigate a page of rows up
+---  * <kbd>^d</kbd> to navigate a page of rows down
 Entity.selectionModalShortcuts = {
     { { "ctrl" }, "j", function(modal) modal:selectedRow(modal:selectedRow() + 1) end },
     { { "ctrl" }, "k", function(modal) modal:selectedRow(modal:selectedRow() - 1) end },
+    { { "ctrl" }, "d", function(modal) modal:selectedRow(modal:selectedRow() + modal:rows()) end },
+    { { "ctrl" }, "u", function(modal) modal:selectedRow(modal:selectedRow() - modal:rows()) end },
 }
 
 --- Entity.showSelectionModal(choices, callback)
diff --git a/src/file.lua b/src/file.lua
index 854392a..fbec15f 100644
--- a/src/file.lua
+++ b/src/file.lua
@@ -1,6 +1,6 @@
 --- === File ===
 ---
---- File class that subclasses [Entity](Entity.html) to represent some directory or file
+--- File class that subclasses [Entity](Entity.html) to represent some directory or file to be automated
 ---
 
 local luaVersion = _VERSION:match("%d+%.%d+")
@@ -100,9 +100,9 @@ function File:initialize(path, shortcuts)
         local commonDirectoryShortcuts = {
             { nil, "c", actions.copy, { path, "Copy File to Folder" } },
             { nil, "d", actions.deleteFileInFolder, { path, "Move File in Folder to Trash" } },
+            { nil, "i", actions.showInfoForFileInFolder, { path, "Open File Info Window" } },
             { nil, "m", actions.move, { path, "Move File to Folder" } },
             { nil, "o", actions.openFileInFolder, { path, "Open File in Folder" } },
-            { nil, "i", actions.showInfoForFileInFolder, { path, "Get File Info for File in Folder" } },
             { nil, "space", actions.quickLookFileInFolder, { path, "Quick Look" } },
             { { "shift" }, "o", actions.openFileInFolderWith, { path, "Open File in Folder with App" } },
         }
@@ -159,7 +159,7 @@ end
 
 --- File:getFileIcon(path) -> [`hs.image`](http://www.hammerspoon.org/docs/hs.image.html)
 --- Method
---- Retrieves an icon image for the given file path or returns nil if not found
+--- Retrieves an icon image for the given file path or returns `nil` if not found
 ---
 --- Parameters:
 ---  * `path` - The path of a file
@@ -299,27 +299,33 @@ function File.open(path)
     end
 end
 
---- File:openWith(path)
+--- File.createFileChoices(fileListIterator, createText, createSubText) -> choice object list
 --- Method
---- Opens a file or directory at the given path with a specified application and raises the application to the front
+--- Creates a list of choice objects each representing the file walked with the provided iterator
 ---
 --- Parameters:
----  * `path` - the path of the target file to open
+---  * `fileListIterator` - an iterator to walk a list of file paths, i.e. `s:gmatch(pattern)`
+---  * `createText` - an optional function that takes in a single `path` argument to return a formatted string to assign to the `text` field in each file choice object
+---  * `createSubText` - an optional function that takes in a single `path` argument to return a formatted string to assign to the `subText` field in each file choice object
 ---
 --- Returns:
----   * None
-function File:openWith(path)
-    local allApplicationsPath = _G.spoonPath.."/bin/AllApplications"
-    local shellscript = allApplicationsPath.." -path \""..path.."\""
-    local output = hs.execute(shellscript)
+---   * `choices` - A list of choice objects each containing the following fields:
+---     * `text` - The primary chooser text string
+---     * `subText` - The chooser subtext string
+---     * `fileName` - The name of the file
+---     * `path` - The path of the file
+function File.createFileChoices(fileListIterator, createText, createSubText)
     local choices = {}
+    local fileNameRegex = "^.+/(.+)$"
 
-    for applicationPath in string.gmatch(output, "[^\n]+") do
-        local bundleInfo = hs.application.infoForBundlePath(applicationPath)
+    for path in fileListIterator do
+        local bundleInfo = hs.application.infoForBundlePath(path)
+        local fileName = path:match(fileNameRegex) or ""
         local choice = {
-            text = applicationPath,
-            subText = applicationPath,
-            applicationPath = applicationPath,
+            text = createText and createText(path) or fileName,
+            subText = createSubText and createSubText(path) or path,
+            fileName = fileName,
+            path = path,
         }
 
         if bundleInfo then
@@ -330,6 +336,24 @@ function File:openWith(path)
         table.insert(choices, choice)
     end
 
+    return choices
+end
+
+--- File:openWith(path)
+--- Method
+--- Opens a file or directory at the given path with a specified application and raises the application to the front
+---
+--- Parameters:
+---  * `path` - the path of the target file to open
+---
+--- Returns:
+---   * None
+function File:openWith(path)
+    local allApplicationsPath = _G.spoonPath.."/bin/AllApplications"
+    local shellscript = allApplicationsPath.." -path \""..path.."\""
+    local output = hs.execute(shellscript)
+    local choices = self.createFileChoices(string.gmatch(output, "[^\n]+"))
+
     -- Defer execution to avoid conflicts with the prior selection modal that just closed
     hs.timer.doAfter(0, function()
         self.showSelectionModal(choices, function(choice)
@@ -338,7 +362,7 @@ function File:openWith(path)
             self:runFileModeApplescript({
                 operation = "open-with",
                 filePath1 = path,
-                filePath2 = choice.applicationPath,
+                filePath2 = choice.path,
             })
         end)
     end)
diff --git a/src/smart-folder.lua b/src/smart-folder.lua
new file mode 100644
index 0000000..e63b3f8
--- /dev/null
+++ b/src/smart-folder.lua
@@ -0,0 +1,222 @@
+--- === SmartFolder ===
+---
+--- SmartFolder class that subclasses [File](File.html) to represent a [smart folder](https://support.apple.com/kb/PH25589) to be automated
+---
+
+local luaVersion = _VERSION:match("%d+%.%d+")
+
+-- luacov: disable
+if not _G.getSpoonPath then
+    function _G.getSpoonPath()
+        return debug.getinfo(2, "S").source:sub(2):match("(.*/)"):sub(1, -2)
+    end
+end
+if not _G.requirePackage then
+    function _G.requirePackage(name, isInternal)
+        local location = not isInternal and "/deps/share/lua/"..luaVersion.."/" or "/"
+        local packagePath = _G.getSpoonPath()..location..name..".lua"
+
+        return dofile(packagePath)
+    end
+end
+-- luacov: enable
+
+local cheatsheet = _G.requirePackage("cheatsheet", true)
+local File = _G.requirePackage("File", true)
+local SmartFolder = File:subclass("File")
+
+--- SmartFolder:initialize(path, shortcuts)
+--- Method
+--- Initializes a new smart folder entity instance with its search criteria file and custom shortcuts. By default, a cheatsheet and default shortcuts are initialized.
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---  * `shortcuts` - The list of shortcuts containing keybindings and actions for the smart folder entity
+---
+--- Each `shortcut` item should be a list with items at the following indices:
+---  * `1` - An optional table containing zero or more of the following keyboard modifiers: `"cmd"`, `"alt"`, `"shift"`, `"ctrl"`, `"fn"`
+---  * `2` - The name of a keyboard key. String representations of keys can be found in [`hs.keycodes.map`](https://www.hammerspoon.org/docs/hs.keycodes.html#map).
+---  * `3` - The event handler that defines the action for when the shortcut is triggered
+---  * `4` - A table containing the metadata for the shortcut, also a list with items at the following indices:
+---    * `1` - The category name of the shortcut
+---    * `2` - A description of what the shortcut does
+---
+--- Returns:
+---  * None
+function SmartFolder:initialize(path, shortcuts)
+    path = hs.fs.pathToAbsolute(path)
+
+    local actions = {
+        copy = function(targetPath) self:copy(targetPath) end,
+        moveToTrash = function(targetPath) self:moveToTrash(targetPath) end,
+        openInfoWindow = function(targetPath) self:openInfoWindow(targetPath) end,
+        move = function(targetPath) self:move(targetPath) end,
+        openFile = function(targetPath) self:openFile(targetPath) end,
+        openFileWith = function(targetPath) self:openFileWith(targetPath) end,
+    }
+    local commonShortcuts = {
+        { nil, nil, self.open, { path, "Open Smart Folder" } },
+        { nil, "c", actions.copy, { path, "Copy File in Smart Folder to a different location" } },
+        { nil, "d", actions.moveToTrash, { path, "Move File in Smart Folder to Trash" } },
+        { nil, "i", actions.openInfoWindow, { path, "Open Info Window for File in Smart Folder" } },
+        { nil, "m", actions.move, { path, "Move File in Smart Folder to a different location" } },
+        { nil, "o", actions.openFile, { path, "Open File in Smart Folder" } },
+        { { "shift" }, "o", actions.openFileWith, { path, "Open Smart Folder File with Application" } },
+        { { "shift" }, "/", actions.showCheatsheet, { path, "Show Cheatsheet" } },
+    }
+
+    local mergedShortcuts = self.mergeShortcuts(shortcuts, commonShortcuts)
+
+    self.path = path
+    self.shortcuts = mergedShortcuts
+    self.cheatsheet = cheatsheet
+
+    local cheatsheetDescription = "Ki shortcut keybindings registered for smart folder at "..self.path
+    self.cheatsheet:init(self.path, cheatsheetDescription, mergedShortcuts)
+end
+
+--- SmartFolder:showFileSearchSelectionModal(path, callback)
+--- Method
+--- Shows a selection modal with smart folder search result choices
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---  * `callback` - The callback function invoked on a file choice selection with a choice object created from [`File.createFileChoices`](File.html#createFileChoices)
+---
+---
+--- Returns:
+---  * None
+function SmartFolder:showFileSearchSelectionModal(path, callback)
+    path = path or self.path
+
+    local output = hs.execute([[
+        mdfind "$(/usr/libexec/PlistBuddy -c 'Print RawQuery' ]]..path..[[)"
+    ]])
+    local choices = self.createFileChoices(string.gmatch(output, "[^\n]+"))
+
+    self.showSelectionModal(choices, callback)
+end
+
+--- SmartFolder:openFile(path)
+--- Method
+--- Open a file from the smart folder search results
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---
+--- Returns:
+---  * None
+function SmartFolder:openFile(path)
+    self:showFileSearchSelectionModal(path, function(choice)
+        if choice then hs.open(choice.path) end
+    end)
+end
+
+--- SmartFolder:copy(path)
+--- Method
+--- Copies a file in the smart folder search results to different folder
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---
+--- Returns:
+---  * None
+function SmartFolder:copy(path)
+    local startingSearchPath = hs.fs.pathToAbsolute("~")
+
+    self:showFileSearchSelectionModal(path, function(choice)
+        if choice then
+            local targetPath = choice.path
+
+            self:navigate(startingSearchPath, function(destinationPath)
+                local question = "Copy \""..targetPath.."\" to \""..destinationPath.."\"?"
+
+                self.triggerAfterConfirmation(question, function()
+                    self:runFileModeApplescript({
+                        operation = "copy",
+                        filePath1 = targetPath,
+                        filePath2 = destinationPath,
+                    })
+                end)
+            end)
+        end
+    end)
+end
+
+--- SmartFolder:moveToTrash(path)
+--- Method
+--- Moves a selected file in the smart folder search results to the Trash
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---
+--- Returns:
+---  * None
+function SmartFolder:moveToTrash(path)
+    self:showFileSearchSelectionModal(path, function(choice)
+        if choice then File:moveToTrash(choice.path) end
+    end)
+end
+
+--- SmartFolder:move(path)
+--- Method
+--- Moves a selected file in the smart folder to a different folder
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---
+--- Returns:
+---  * None
+function SmartFolder:move(path)
+    local startingSearchPath = hs.fs.pathToAbsolute("~")
+
+    self:showFileSearchSelectionModal(path, function(choice)
+        if choice then
+            local targetPath = choice.path
+
+            self:navigate(startingSearchPath, function(destinationPath)
+                local question = "Move \""..targetPath.."\" to \""..destinationPath.."\"?"
+
+                self.triggerAfterConfirmation(question, function()
+                    self:runFileModeApplescript({
+                        operation = "move",
+                        filePath1 = targetPath,
+                        filePath2 = destinationPath,
+                    })
+                end)
+            end)
+        end
+    end)
+end
+
+--- SmartFolder:openFileWith(path)
+--- Method
+--- Open a file selected from the smart folder search results with a specific application
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---
+--- Returns:
+---  * None
+function SmartFolder:openFileWith(path)
+    self:showFileSearchSelectionModal(path, function(choice)
+        if choice then File:openWith(choice.path) end
+    end)
+end
+
+--- SmartFolder:openInfoWindow(path)
+--- Method
+--- Opens a Finder information window for the file selected from the smart folder search results
+---
+--- Parameters:
+---  * `path` - The path of the smart folder (`.savedSearch` file)
+---
+--- Returns:
+---  * None
+function SmartFolder:openInfoWindow(path)
+    self:showFileSearchSelectionModal(path, function(choice)
+        if choice then File:openInfoWindow(choice.path) end
+    end)
+end
+
+return SmartFolder

From 728e158da526cad8b607981cd5f1a425ee993745 Mon Sep 17 00:00:00 2001
From: Andrew Kwon <andrewshky@gmail.com>
Date: Sun, 17 Feb 2019 01:14:21 -0800
Subject: [PATCH 5/5] Add System Preferences selection & update defaults

- Update System Preferences entity and add to default select mode events
- Add Volumes folder to default file events
- Add disk utility application entity
---
 src/defaults.lua                              |   4 +
 src/entities/disk-utility.lua                 |  15 ++
 src/entities/system-preferences.lua           |  41 +++++
 src/osascripts/system-preferences.applescript | 158 ++++++++++++++++++
 4 files changed, 218 insertions(+)
 create mode 100644 src/entities/disk-utility.lua
 create mode 100644 src/osascripts/system-preferences.applescript

diff --git a/src/defaults.lua b/src/defaults.lua
index 08b97a7..7ac356b 100644
--- a/src/defaults.lua
+++ b/src/defaults.lua
@@ -33,6 +33,7 @@ local entities = {
     Calculator = _G.requirePackage("entities/calculator", true),
     Contacts = _G.requirePackage("entities/contacts", true),
     Dictionary = _G.requirePackage("entities/dictionary", true),
+    DiskUtility = _G.requirePackage("entities/disk-utility", true),
     FaceTime = _G.requirePackage("entities/facetime", true),
     Finder = _G.requirePackage("entities/finder", true),
     GoogleChrome = _G.requirePackage("entities/google-chrome", true),
@@ -87,6 +88,7 @@ function Defaults.createFileEvents()
         { nil, "m", File:new("~/Movies"), { "Files", "Movies" } },
         { nil, "p", File:new("~/Pictures"), { "Files", "Pictures" } },
         { nil, "t", File:new("~/.Trash"), { "Files", "Trash" } },
+        { nil, "v", File:new("/Volumes"), { "Files", "Volumes" } },
         { { "cmd" }, "a", openFinderAppEvent("Airdrop"), { "Files", "Airdrop" } },
         { { "cmd" }, "c", openFinderAppEvent("Computer"), { "Files", "Computer" } },
         { { "cmd" }, "i", openFinderAppEvent("iCloud\\ Drive"), { "Files", "iCloud Drive" } },
@@ -129,6 +131,7 @@ function Defaults.createEntityEvents()
         { nil, "t", entities.Terminal, { "Entities", "Terminal" } },
         { nil, "v", entities.VoiceMemos, { "Entities", "Voice Memos" } },
         { nil, ",", entities.SystemPreferences, { "Entities", "System Preferences" } },
+        { { "cmd" }, "d", entities.DiskUtility, { "Entities", "Disk Utility" } },
         { { "alt", "cmd" }, "s", entities.Siri, { "Entities", "Siri" } },
         { { "shift" }, "a", entities.ActivityMonitor, { "Entities", "Activity Monitor" } },
         { { "shift" }, "c", entities.Calculator, { "Entities", "Calculator" } },
@@ -153,6 +156,7 @@ function Defaults.createEntityEvents()
         { nil, "p", entities.Preview, { "Select Events", "Select a Preview window" } },
         { nil, "s", entities.Safari, { "Select Events", "Select a Safari tab or window" } },
         { nil, "t", entities.Terminal, { "Select Events", "Select a Terminal window" } },
+        { nil, ",", entities.SystemPreferences, { "Entities", "Select a System Preferences pane" } },
         { { "shift" }, "t", entities.TextEdit, { "Select Events", "Select a Text Edit window" } },
     }
 
diff --git a/src/entities/disk-utility.lua b/src/entities/disk-utility.lua
new file mode 100644
index 0000000..6725368
--- /dev/null
+++ b/src/entities/disk-utility.lua
@@ -0,0 +1,15 @@
+local Application = dofile(_G.spoonPath.."/application.lua")
+
+local actions = {
+    newBlankImage = Application.createMenuItemEvent("Blank Image...", { focusAfter = true }),
+    newImageFromFolder = Application.createMenuItemEvent("Image From Folder...", { focusAfter = true }),
+    openDiskImage = Application.createMenuItemEvent("Open Disk Image...", { focusAfter = true }),
+}
+
+local shortcuts = {
+    { nil, "n", actions.newBlankImage, { "File", "New Blank Image" } },
+    { nil, "o", actions.openDiskImage, { "File", "Open Disk Image" } },
+    { { "shift" }, "n", actions.newImageFromFolder, { "File", "New Image From Folder" } },
+}
+
+return Application:new("Disk Utility", shortcuts), shortcuts, actions
diff --git a/src/entities/system-preferences.lua b/src/entities/system-preferences.lua
index e7df074..05cce8c 100644
--- a/src/entities/system-preferences.lua
+++ b/src/entities/system-preferences.lua
@@ -4,7 +4,48 @@ local actions = {
     showAllPreferences = Application.createMenuItemEvent("Show All Preferences", { focusBefore = true }),
 }
 
+function Application.getSelectionItems()
+    local choices = {}
+    local script = Application.renderScriptTemplate("system-preferences", { option = "fetch-panes" })
+    local isOk, panes, rawTable = hs.osascript.applescript(script)
+
+    if not isOk then
+        Application.notifyError("Error fetching System Preferences panes", rawTable.NSLocalizedFailureReason)
+    end
+
+    for paneId, paneName in pairs(panes) do
+        table.insert(choices, {
+            paneId = paneId,
+            text = paneName,
+            subText = paneId,
+        })
+    end
+
+    table.sort(choices, function(a, b)
+        return a.text < b.text
+    end)
+
+    return choices
+end
+
+function actions.focus(app, choice)
+    app:activate()
+
+    if choice then
+        local script = Application.renderScriptTemplate("system-preferences", {
+            option = "reveal-pane",
+            targetPane = choice.paneId,
+        })
+        local isOk, _, rawTable = hs.osascript.applescript(script)
+
+        if not isOk then
+            Application.notifyError("Error revealing System Preferences pane", rawTable.NSLocalizedFailureReason)
+        end
+    end
+end
+
 local shortcuts = {
+    { nil, nil, actions.focus, { "View", "Activate/Focus" } },
     { nil, "l", actions.showAllPreferences, { "View", "Show All Preferences" } },
     { { "cmd" }, "f", actions.search, { "View", "Search" } },
 }
diff --git a/src/osascripts/system-preferences.applescript b/src/osascripts/system-preferences.applescript
new file mode 100644
index 0000000..4e5a3d7
--- /dev/null
+++ b/src/osascripts/system-preferences.applescript
@@ -0,0 +1,158 @@
+-- AppleScript template for various system preferences options
+-- `option` - the name of the option
+-- `targetPane` - the target pane to reveal
+set option to "{{option}}"
+set targetPane to "{{targetPane}}"
+
+tell application "System Preferences"
+
+	if option is "fetch-panes" then
+
+		set paneIdsByName to {}
+
+		repeat with prefPane in panes
+			set paneId to id of prefPane
+			set paneName to name of prefPane as string
+
+            set AppleScript's text item delimiters to {return & linefeed, return, linefeed, character id 8233, character id 8232}
+            set paneName to text items of paneName
+            set AppleScript's text item delimiters to {" "}
+            set paneName to paneName as text
+
+			set paneRecord to run script "{|" & paneId & "|:\"" & (paneName as string) & "\"}"
+			set paneIdsByName to paneIdsByName & paneRecord
+		end repeat
+
+		return paneIdsByName
+
+    else if option is "reveal-pane" then
+
+        reveal pane targetPane
+
+    else if option is "Accessibility" then
+
+        reveal pane "com.apple.preference.universalaccess"
+
+    else if option is "Bluetooth" then
+
+        reveal pane "com.apple.preferences.bluetooth"
+
+    else if option is "Date & Time" then
+
+        reveal pane "com.apple.preference.datetime"
+
+    else if option is "Desktop & Screen Saver" then
+
+        reveal pane "com.apple.preference.desktopscreeneffect"
+
+    else if option is "Displays" then
+
+        reveal pane "com.apple.preference.displays"
+
+    else if option is "Dock" then
+
+        reveal pane "com.apple.preference.dock"
+
+    else if option is "Energy Saver" then
+
+        reveal pane "com.apple.preference.energysaver"
+
+    else if option is "Extensions" then
+
+        reveal pane "com.apple.preferences.extensions"
+
+    else if option is "General" then
+
+        reveal pane "com.apple.preference.general"
+
+    else if option is "iCloud" then
+
+        reveal pane "com.apple.preferences.icloud"
+
+    else if option is "Internet Accounts" then
+
+        reveal pane "com.apple.preferences.internetaccounts"
+
+    else if option is "Keyboard" then
+
+        reveal pane "com.apple.preference.keyboard"
+
+    else if option is "Language & Region" then
+
+        reveal pane "com.apple.localization"
+
+    else if option is "Mission Control" then
+
+        reveal pane "com.apple.preference.expose"
+
+    else if option is "Mouse" then
+
+        reveal pane "com.apple.preference.mouse"
+
+    else if option is "Network" then
+
+        reveal pane "com.apple.preference.network"
+
+    else if option is "Notifications" then
+
+        reveal pane "com.apple.preference.notifications"
+
+    else if option is "Parental Controls" then
+
+        reveal pane "com.apple.preferences.parentalcontrols"
+
+    else if option is "Printers & Scanners" then
+
+        reveal pane "com.apple.preference.printfax"
+
+    else if option is "Security & Privacy" then
+
+        reveal pane "com.apple.preference.security"
+
+    else if option is "Sharing" then
+
+        reveal pane "com.apple.preferences.sharing"
+
+    else if option is "Siri" then
+
+        reveal pane "com.apple.preference.speech"
+
+    else if option is "Software Update" then
+
+        reveal pane "com.apple.preferences.softwareupdate"
+
+    else if option is "Sound" then
+
+        reveal pane "com.apple.preference.sound"
+
+    else if option is "Spotlight" then
+
+        reveal pane "com.apple.preference.spotlight"
+
+    else if option is "Startup Disk" then
+
+        reveal pane "com.apple.preference.startupdisk"
+
+    else if option is "Time Machine" then
+
+        reveal pane "com.apple.prefs.backup"
+
+    else if option is "Touch ID" then
+
+        reveal pane "com.apple.preferences.password"
+
+    else if option is "Trackpad" then
+
+        reveal pane "com.apple.preference.trackpad"
+
+    else if option is "Users & Groups" then
+
+        reveal pane "com.apple.preferences.users"
+
+    else if option is "Wallet & Apple Pay" then
+
+        reveal pane "com.apple.preferences.wallet"
+
+	end if
+
+end tell