Setting up ProjectShelf on macOS

ProjectShelf ships with Windows-oriented presets because that is where it was built. Every one of them is an ordinary entry you can edit or delete, so the first thing to do on a Mac is replace them with your own. It takes about five minutes and you only do it once.

Add your terminal

Go to Settings, then Terminals. Delete or disable PowerShell, Command Prompt, Git Bash, and Windows Terminal, then add the shell you actually use. The two fields that matter are the executable and the directory change prefix.

The prefix is how your shell changes directory. On macOS that is plain cd for zsh, bash, and fish alike, which is why the Command Prompt preset with its cd /d is wrong for you. With the prefix set, opening a project in the terminal produces this:

cd "/Users/you/Projects/aurora"

If you use Warp, Ghostty, Alacritty, or Kitty, add each as its own terminal. They all take the same cd prefix, so the only thing that differs is the name and the executable path.

Add your editor

Editors are configured in Settings, then Editors. Each one has an open command, which is a template with placeholders that get filled in per project. Most macOS editors ship a command line launcher you have to install once.

1. 1

   Install the VS Code command line tool

   Open VS Code, press Command and Shift and P together, type "shell command", and choose Install code command in PATH. Cursor and Windsurf have the same option under their own names.

2. 2

   Check it works

   In a terminal, run the launcher against any folder. If the editor opens, ProjectShelf can generate the same command.

   code ~/Projects

3. 3

   Add the editor in ProjectShelf

   In Settings, then Editors, add an entry with the open command below. The {path} placeholder is replaced with each project folder.

   code "{path}"

Replace Explorer with Finder

Under Settings, then Applications, there is a Finder entry that ships disabled and a Windows Explorer entry that ships enabled. Switch them around: enable Finder, disable Explorer, then set Finder as your default file manager under Settings, then General.

A note about paths

Store full paths starting from the root, such as /Users/you/Projects/aurora. A tilde works in your shell but not in every tool, and ProjectShelf copies the path exactly as you saved it. Paths with spaces are fine because the presets already wrap {path} in quotes; keep those quotes in any template you write yourself.

Shortcuts and the Command key

Shortcuts written with Ctrl also respond to Command on a Mac, so the defaults work without changes. If you would rather record them as Command explicitly, go to Settings, then Shortcuts, select any binding, and press the combination you want. Conflicts are flagged as you record.

Install it as an app

In Safari, use Share and then Add to Dock. In Chrome or Edge, use the install icon in the address bar, or the Install app button in the ProjectShelf sidebar when it appears. Installed, it opens in its own window and works without a network connection.