Welcome to Hermit Crab

Hermit Crab is a tool for quickly running shell commands without switching over to a full terminal app. It is designed to be invoked as a service via a global keyboard shortcut. The following instructions will explain how to set this up.

Set up window detection

Hermit Crab uses Accessibility features to find the frontmost window and check what file or folder it has open, in order to position its own window and set the current directory. It additionally uses automation features (Apple Events) to detect the currently open folder in Finder, which doesn’t respond to the usual Accessibility mechanisms. Hermit Crab does not store this information anywhere and will never look at the contents of an open file.

Open System Preferences.
Choose the “Privacy” tab in the “Security” preferences pane.
Enable “Hermit Crab” under “Accessibility”. If it’s not there, try quitting System Preferences, activating Finder, opening Hermit Crab, then reopening System Preferences.

You can revoke Hermit Crab’s permissions at any time by returning to the “Security” preferences pane. Hermit Crab will still allow you to run commands without these permissions; it will just use your home directory as the working directory.

Set up a global keyboard shortcut (optional)

To set up a global shortcut for Hermit Crab, follow the steps below.

Open System Preferences.
Choose the “Shortcuts” tab in the “Keyboard” preferences pane.
Click on “Activate Hermit Crab” in the “General” section under “Services”. If it’s not there, try quitting System Preferences, opening Hermit Crab directly, then reopening System Preferences.
Click the “Add Shortcut” button that appears.
Type the key combination you wish to use to activate Hermit Crab. (Recommended: ⌃⌘\ )

If you ever want to remove the shortcut, click the shortcut keys again and press Delete.

Keyboard shortcuts

Action	Shortcut
Run command	↩︎
Run in Terminal	⌘↩︎
Cancel running command	⌘.
Show previous command	⌥⌘←
Show next command	⌥⌘→
Reuse command	⌥⌘↑
Copy results	⇧⌘C

Troubleshooting

Hermit Crab can’t find the current window when I activate it from Finder.

“Run in Terminal” doesn’t work.

Both of these features uses automation (Apple Events) to open a new Terminal window and run your command in it. On macOS Mojave and later, you’ll be prompted for permission when you first try to use these features, but if you have previously denied permission and want to change your mind, follow the steps below. Hermit Crab will never look at the contents of your Finder or Terminal windows.

Open System Preferences.
Choose the “Privacy” tab in the “Security” preferences pane.
Enable Hermit Crab’s “Finder” or “Terminal” entry under “Automation”. If it’s not there, try quitting System Preferences, opening Hermit Crab from the Finder, choosing the “Run in Terminal” command from the Action menu, then reopening System Preferences.

You can revoke Hermit Crab’s permissions at any time by returning to the “Security” preferences pane. Hermit Crab will still allow you to run commands in its own window.

Commands are running slowly.

Hermit Crab uses a non-interactive login shell to run commands so that your custom environment variables are set up correctly (including PATH). If trivial commands like echo hello are slow to complete, it’s possible your shell’s startup files (.zlogin and such) contain an operation that takes a while to run. You can check if this is the case by running echo | time login -f $USER in Terminal; if it takes more than maybe 10ms, it’s probably noticeable in Hermit Crab. To fix this, modify your startup files to only do complex work...

...in “interactive-only” startup files like .zshrc and .bashrc, if your shell has them.
...when the current shell is interactive: test -z "${-##*i*}" (does $- contain "i")
...when not running under Hermit Crab: test -z "$HERMIT_CRAB"

If your startup files are not causing the slowdown, please report the issue to hermitcrab@belkadan.com.

Notes

Why isn’t Hermit Crab notarized by Apple?: Ideological reasons. I’ve written more about this decision as well, but it comes down to being uncomfortable with Apple’s choices for app development on Macs.
Why is it called Hermit Crab?: Hermit crabs are a kind of crustacean that use the shells of other animals for protection. That is, a hermit crab can use a shell from anywhere.

Contact

hermitcrab@belkadan.com: Bugs, requests, questions? Email us!
belkadan.com: Watch for more programs from Belkadan Software.

Credits

Icon designed by brgfx / Freepik, used under the Freepik License.

Updates provided via Sparkle (license).

Some code adapted from the LLVM project under the University of Illinois/NCSA Open Source License.

Inspired by Decimus Software’s DTerm. Thank you for many years of a useful tool!

Belkadan Software