Finda setup

Finda integrates with a wide variety of sources, so you can find all the things. If you’d like to see another integration, please write and we’ll look into it!

Within Finda, hold the “Command” key to see all available keyboard shortcuts (including toggling integrations on or off).

For a better overall Finda / computing experience, you may also want to eliminate the OS X fullscreen animation.

Finda’s global shortcut key can be edited via ~/.finda/shortcut.conf.

Font sizes and colors can be edited via ~/.finda/theme.css.

Current integrations:


Finda searches all of the directories listed in ~/.finda/paths_to_search.conf, which defaults to /Applications/ so that you can open apps.

You can add as many paths as you like:

Finda does not use OS X spotlight whatsoever, because it’s too slow. Instead, it walks these directories itself to list files.

Finda respects rules in .gitignore files, so you can use these to filter filesystem results.

When you select a filesystem result, Finda runs the OS X open command on the path. So if you want a specific program to open up certain kinds of files, set the default via the “get info” OS X option. Here’s a video.


Finda lists all iTerm sessions (windows > tabs > splits). You’ll need to copy the Finda plugin into iTerm’s scripts directory:

mkdir -p ~/"Library/Application Support/iTerm2/Scripts/AutoLaunch/"
cp ~/.finda/integrations/ ~/"Library/Application Support/iTerm2/Scripts/AutoLaunch/"


No setup is required to show OS X windows. All windows — including minimized windows and windows on other workspaces — can be found by Finda.


Finda integrates with Emacs 25.1 and later. Add to your ~/.emacs.d/init.el file the line:

(load "~/.finda/integrations/emacs/finda.el")

You should also have emacsclient in /usr/local/bin. (This is already the case if you installed Emacs via brew cask install emacs.)

Finda invokes emacsclient with its default socket settings, so make sure you haven’t set Emacs’s server-socket-dir to a custom value.

Visual Studio Code

Finda integrates with Visual Studio Code (tested with 1.21.1, but likely works with older versions too).

Open the command palette (default hotkey: shift command p), select “Extensions: Install from VSIX”, and choose ~/.finda/integrations/visual_studio_code_extension.vsix. Restart Code as prompted.

Note: Code lazily loads documents, so when first opening Code it may display tabs in its own UI that aren’t listed in Finda. After you’ve switched to these tabs at least once, Code will actually load the document and it will show up in Finda. See this Github issue for details.

Sublime Text

Finda integrates with Sublime Text 3 (tested with build 3143, but likely works with older versions too). Install the package by copying it to the Sublime package directory:

cp ~/.finda/integrations/finda.sublime-package ~/"Library/Application Support/Sublime Text 3/Installed Packages/"

and restart Sublime Text.

Chrome and Firefox tabs

Broswer tab results are powered by a Finda browser extension. The extension needs to “Read and change all your data on the websites you visit” so that it can take page screenshots to show you in Finda. (Feel free to read the unminified JavaScript.)

Safari is not supported because it only accepts extensions that use a proprietary API, distributed via the Mac App store.

For Chrome, type chrome://extensions/ in the URL bar, check the “developer mode” box, click “Load unpacked extension” and select ~/.finda/integrations/browser_extension

For Firefox, type about:addons into the URL bar, click the gear icon, and select “Install Add-on from File” and select ~/.finda/integrations/firefox_extension.xpi.

Chrome and Firefox history

No setup necessary. Finda automatically reads history from both Chrome and Firefox.

Selecting a history result opens the URL in your system’s default browser.

External Data (JSON)

You can add your own arbitrary data to Finda by writing JSON files to ~/.finda/external_data/. Each file may contain a single map or an array of maps. Each map will be checked for the following keys:

Any extra keys will be ignored, as will any files that cannot be parsed as JSON.

Files will be searched for changes on every Finda show/hide — you do not need to restart Finda to refresh JSON results.

For example, creating the file ~/.finda/external_data/foo.json containing:

  {"label": "Visit @lynaghk on Github",
   "command": "open",
   "icon": ""},

  {"label": "Play some space music",
   "command": "/Applications/"}

will add results for quickly jumping to Kevin’s Github profile and for playing ambient space music.

A note on fullscreen

OS X Spaces is a “feature” that adds a swiping animation each time you switch between fullscreen applications.

Finda will appear without animation on your current space, but it cannot prevent the swipe animation when switching to an application on another space.

If a gratuitous 500ms animation is an affront to your dignity (or if it just makes you seasick), you are not alone. Many app developers have introduced specific workarounds to allow their apps to fullscreen on the default space.

In Emacs, set

(setq ns-use-native-fullscreen nil)

Then you can toggle humane fullscreen via toggle-frame-fullscreen.

In ITerm2, open preferences and uncheck “Native fullscreen windows”.

In Google Chrome, throw yourself upon the mercy of Google developers on this Chromium bug ticket.

For everything else, pay $12 for Total Spaces2, which somehow injects code into OS X itself to actually disable the animation.