Help

How to use Haunts

Hit ⌥Space, type a couple of letters, land in the project. Everything else is optional.

Install

  1. Download the latest .dmg from gethaunts.app (current version v0.1.2).
  2. Open the disk image and drag Haunts into your Applications folder.
  3. Launch Haunts from Applications. It runs in the menu bar, with no Dock icon and no window until you summon one.

Haunts requires macOS 14+ (Sonoma or later). It auto-updates in the background via Sparkle.

First-launch permissions

The first time Haunts needs to open something in Finder, macOS will show the standard Automation (Finder) consent prompt. Allow it once and Haunts can hand paths to Finder from then on. You can review or revoke it any time in System Settings, Privacy & Security, Automation.

That is the only permission Haunts asks for. It reads folder paths locally to build its ranking, and the index never leaves your Mac. See Privacy for the full note.

The basics

Haunts is a focused navigator. The whole flow is three steps:

  1. Summon, press ⌥Space anywhere. The palette appears at the top of your screen.
  2. Narrow, type a couple of letters. The list is already warm and pre-ranked, so a fuzzy match usually puts what you want at the top.
  3. Land, press ↩ to open in Finder, ⌘↩ to open in your editor, or ⌃↩ to open in a terminal.

Press Esc to dismiss the palette. It is a window only when you ask for it. Close it and Haunts is back to being a menu-bar icon.

"Warm on first launch"

You do not have to teach Haunts where you work. On first run it seeds its ranking from signals already on your Mac (your recent folders, projects, and the places macOS already knows you visit) and rolls deep paths up to the nearest .git root. The first time you open the palette, your real projects are already near the top.

Keyboard shortcuts

Everything in Haunts is reachable from the keyboard.

  • ⌥Space, summon the palette (rebindable).
  • ↑ / ↓, move through the list.
  • ↩, open the selected place in Finder.
  • ⌘↩, open it in your chosen editor.
  • ⌃↩, open it in your chosen terminal.
  • ⌘⌫, remove the selected entry from Haunts' cache (see Forgetting a place).
  • Esc, dismiss the palette.

Forgetting a place

Highlight an entry in the palette and press ⌘⌫ to delete it from Haunts' cache. It disappears from the list immediately and stops influencing the ranking. Use this for one-off folders that crept in, projects you have archived, or anything you simply do not want to see again. If Haunts picks the place back up from a scan root later (because you visit it again), it will start from a clean slate.

Settings

Open Settings from the Haunts menu-bar icon. Everything is optional (Haunts works well out of the box), but here is what you can change.

Hotkey

The default summon shortcut is ⌥Space. Rebind it to anything that does not clash with another global shortcut. If a hotkey stops working after an OS update, it is usually because another app has grabbed the same combination. Change it here.

Scan roots

Scan roots are the folders Haunts looks inside when it builds and refreshes its list of places. Sensible defaults are set on first launch (your home folder and the usual suspects). Add a root for any directory tree you want surfaced (for example a ~/Code or ~/Work folder), and remove ones you do not care about.

Haunts down-weights transient folders (like ~/Downloads) automatically, so you do not have to babysit the ranking.

Editor & terminal

Pick the app Haunts should hand paths to when you press ⌘↩ (editor) and ⌃↩ (terminal). Most popular editors and terminals are recognised (VS Code, Cursor, Zed, Sublime Text, IntelliJ, Terminal.app, iTerm2, Ghostty, WezTerm, Alacritty, and friends). If yours is not listed, point Haunts at the application bundle directly.

Ranking mode

Haunts ships with two ranking modes:

  • Balanced (default), frecency: frequency × recency. The places you keep coming back to surface to the top, and a recent visit can lift something quickly.
  • Frequent, z-style ranking that leans harder on raw frequency, the way the terminal z / zoxide tool does. Use this if you want long-term favourites to be stickier.

Appearance

Haunts follows your system appearance (light or dark) automatically. There is no appearance toggle to fiddle with.

Tips

  • Type the project, not the path. A couple of letters of the project name almost always beats typing the path. Haunts is fuzzy and project-aware.
  • Trust the top. When the palette opens, the place you want is usually already selected. Just press ↩.
  • Prune as you go. If something you do not want keeps appearing, hit ⌘⌫ to forget it.
  • Make new haunts. The more often you land somewhere via Haunts, the more it learns. After a week or two it feels like muscle memory.
  • Lean on the three openings. Same list, three doors: Finder for a peek, editor for work, terminal for the command line.

Updates

Haunts checks for and installs its own updates via Sparkle. You will get a quiet prompt when a new version is available; accept it and the app restarts into the update. See the changelog for what is in each release.

Troubleshooting

The hotkey does not do anything

Another app has probably claimed the same combination, or macOS has not granted Accessibility / Input Monitoring permission. Open Settings from the menu-bar icon and either rebind the hotkey or check System Settings, Privacy & Security for any prompts Haunts is waiting on.

Pressing ↩ does not open Finder

That is the Automation prompt waiting in the wings. Trigger it once, accept the Automation (Finder) consent, and it will just work from then on. If you dismissed the prompt earlier, re-enable it in System Settings, Privacy & Security, Automation.

My project is not in the list

Check your scan roots. The folder needs to live under one of them. If it does, open it once via Finder; Haunts will pick it up and start ranking it from there.

A place I deleted keeps coming back

⌘⌫ removes an entry from the cache, but if the folder still sits under one of your scan roots and you visit it again, Haunts will pick it up on the next refresh. Either stop visiting it, or narrow your scan roots so the folder is not in scope.

The wrong editor / terminal opens

Set the editor and terminal you want under Settings, Editor & terminal. Haunts honours your choice for ⌘↩ and ⌃↩ regardless of system defaults.

Something else is off

Please open an issue on GitHub with what you saw and what you expected. It really does help.

More

Missing something? Open an issue, Haunts v0.1.2.