Make Raycast find the Mac apps you build in Xcode

By

Build your Xcode apps into the project folder, let App Drawer keep a shortcut for each one, and open the newest build from Raycast's main search.

You built a Mac app in Xcode, you open Raycast, type its name, and nothing comes up. Or worse, Raycast finds an old copy you dragged to /Applications weeks ago, and you spend five minutes wondering why your fix isn’t there.

Raycast doesn’t look inside Xcode’s build folders, and Xcode doesn’t install anything. By default it puts every build in ~/Library/Developer/Xcode/DerivedData, inside a folder named after the project plus a random-looking suffix. Copying the build to /Applications after every change works, but the copy goes stale the minute you build again.

App Drawer fixes the second half. It finds the .app builds in your project folders and keeps a shortcut to the newest one of each in ~/Applications/App Drawer Apps, so Raycast can find them in its main search. The first half is on you: the build has to live in the project folder, not in DerivedData.

At the end, typing an app’s name in Raycast opens the build you made a minute ago, with no copying.

What you need

App Drawer needs macOS 14 or later, on Apple silicon or Intel. After you pay, download App-Drawer-1.1.0.zip from your Polar receipt, unzip it, and move App Drawer.app to Applications. The receipt always has the latest version. The first time you open it, macOS asks if you’re sure, and you click Open.

You also need Xcode, for xcodebuild, and Raycast. I ran the commands here with Xcode 26.2.

The appdrawer command ships inside the app. Link it onto your PATH so you can check things from the terminal:

ln -s "/Applications/App Drawer.app/Contents/Helpers/appdrawer" ~/.local/bin/appdrawer

Then, as a preflight check, ask it for its version:

appdrawer --version
appdrawer 1.1.0

If you get command not found, ~/.local/bin isn’t on your PATH yet. Add it in your shell config and open a new Terminal window.

The project in this tutorial is an example: a Mac app called Marble, in /Users/flavio/dev/marble, with the scheme Marble and the bundle ID dev.flavio.marble. The other app names in the output are examples too. Use your own project path and scheme everywhere you see them.

If you’ve never used App Drawer, Find and open the Mac apps you build without cluttering the Dock covers the panel, pins and the Dock. Here we only care about Raycast.

Find where Xcode put your build

Before you change anything, it helps to see why Raycast can’t find the app. Xcode keeps build products, indexes and intermediate files in a DerivedData folder, one per project. That folder isn’t in /Applications or ~/Applications, and it isn’t in your project folder either. So neither Raycast nor App Drawer looks there. App Drawer walks only the folders you give it, and DerivedData sits in your Library. Knowing the real path also tells you which old builds are lying around, and whether you’ve been opening one of them by mistake.

List the DerivedData folders:

ls ~/Library/Developer/Xcode/DerivedData
CompilationCache.noindex
Marble-dkqzrwhyuxbtnlapsvmocgfejiqa
ModuleCache.noindex
SDKStatCaches.noindex
SymbolCache.noindex

The .noindex folders are Xcode’s caches. The suffix after the project name is generated by Xcode, so yours will differ. Now find the app inside it:

find ~/Library/Developer/Xcode/DerivedData -maxdepth 5 -name "*.app" -path "*/Build/Products/*"
/Users/flavio/Library/Developer/Xcode/DerivedData/Marble-dkqzrwhyuxbtnlapsvmocgfejiqa/Build/Products/Debug/Marble.app

That’s the build Xcode’s Run button made. It’s a perfectly good app, it’s just in a place nothing indexes. You don’t need to delete it. We’ll make a second build in the project folder and point everything at that one.

Build into the project folder

xcodebuild takes a -derivedDataPath option, which xcodebuild -help describes as “the directory where build products and other derived data will go”. Give it a folder inside the project, and the .app lands where App Drawer walks. Without it, every terminal build goes to DerivedData too, and App Drawer never sees it. The folder name matters a little. App Drawer skips hidden folders, except .build, and folders named old, archive, backup, backups or vendor. A plain build folder is fine.

First, check the scheme name, because that’s the part people get wrong:

cd /Users/flavio/dev/marble
xcodebuild -list
Command line invocation:
    /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -list

Information about project "Marble":
    Targets:
        Marble

    Build Configurations:
        Debug
        Release

    If no build configuration is specified and -scheme is not passed then "Debug" is used.

    Schemes:
        Marble

Then build into build/:

xcodebuild -scheme Marble -configuration Debug -derivedDataPath build build

The output is long. The last line is the one you want:

** BUILD SUCCEEDED **

And here’s the app:

find build -maxdepth 5 -name "*.app"
build/Build/Products/Debug/Marble.app

The product name is the app’s display name, so a project called lunar-calendar can give you Lunar Calendar.app. That’s fine, App Drawer reads the name from the bundle.

The build folder is generated, so keep it out of Git:

echo "build/" >> .gitignore

Example 1: the main path. I built Marble with the command above at 9:12. The app is at build/Build/Products/Debug/Marble.app, five levels inside the project. App Drawer looks up to 8 levels deep, so it’s well within reach. The next steps check that App Drawer picked it up and made the shortcut.

To undo this step, delete the build folder. It only holds what xcodebuild generated, and the next build recreates it. It’s still a delete, so check you’re in the project folder first.

Check that App Drawer walks that folder

App Drawer finds builds only inside the folders in its list. On the first run that’s ~/dev, ~/Developer, ~/Projects and ~/www, whichever of them exist. Each folder inside those counts as a project. If your project lives in ~/Code, your build can be perfect and App Drawer still won’t see it, so there’s no shortcut and nothing for Raycast to find. Checking the list takes a second and rules out the most common reason a build is missing.

appdrawer folders
~/dev
(the defaults)

(the defaults) means you haven’t picked folders yourself. Marble is in ~/dev, so we’re covered. If yours isn’t, add the parent folder:

appdrawer folders add ~/Code
Added ~/Code.

Run it a second time and it prints Already walking ~/Code. without changing anything. It also checks every folder exists before it touches the list, so a typo can’t leave you with half a change. To undo, appdrawer folders remove ~/Code prints Removed ~/Code., and appdrawer folders reset goes back to the defaults.

A running App Drawer picks up the change right away. Now ask for the list the panel shows:

appdrawer list --filter all
Working On:
  Marble	12 minutes ago

All Apps (all):
  Field Notes	3 days ago
  Harbor Notes	last week
  Marble	12 minutes ago
  ---- idle for 60 days
  Copper	4 months ago

Marble is in Working On because it was built in the last 16 hours. The time is the newest of the build and the last commit. If you just built and Marble isn’t there, App Drawer may not have walked the folders since. It does a full walk at launch and again when five minutes have passed, and File → Rescan Apps (⌘R) forces one.

Here’s the whole chain, from your build to Raycast:

How an Xcode build reaches Raycastxcodebuild writes the app into a build folder inside the project. App Drawer walks the project folders, keeps the newest build per bundle ID and writes a shortcut to it in Applications/App Drawer Apps, which Raycast's main search can find.NoYesYesNoxcodebuild-derivedDataPathbuildproject/build/Build/Products/Debug/Marble.appProject inside anApp Drawer folder?Not found: appdrawerfolders addNewest build perbundle IDHidden?No shortcutShortcut in~/Applications/AppDrawer AppsRaycast main search

Look at the shortcuts Raycast finds

App Drawer doesn’t copy your builds anywhere. It makes a symbolic link for each app it lists, in ~/Applications/App Drawer Apps, and Raycast finds those. A link costs nothing on disk, and it always points at a real build, so you never open a stale copy. It’s worth looking at once, because it explains every later behavior: what happens when you rebuild, when you hide an app, and when two apps share a name. File → Show Raycast Apps Folder writes the shortcuts again and opens the folder in the Finder. From the terminal:

ls ~/Applications/"App Drawer Apps"
Copper.app
Field Notes.app
Harbor Notes.app
Marble.app

Each entry is a link. readlink shows where one goes:

readlink ~/Applications/"App Drawer Apps"/Marble.app
/Users/flavio/dev/marble/build/Build/Products/Debug/Marble.app

App Drawer also keeps a hidden file in that folder, .appdrawer-links.json, that lists the links it made. It’s one line of JSON, with the slashes escaped:

cat ~/Applications/"App Drawer Apps"/.appdrawer-links.json
{"Copper.app":"\/Users\/flavio\/dev\/copper\/dist\/Copper.app","Field Notes.app":"\/Users\/flavio\/dev\/field-notes\/build\/Build\/Products\/Release\/Field Notes.app","Harbor Notes.app":"\/Users\/flavio\/dev\/harbor-notes\/dist\/Harbor Notes.app","Marble.app":"\/Users\/flavio\/dev\/marble\/build\/Build\/Products\/Debug\/Marble.app"}

That file is the safety catch. App Drawer only replaces or removes a link that’s in the manifest and still points where it left it. If you put your own file or link in that folder with the same name, App Drawer never overwrites it. Other files in the folder stay put.

Two apps with the same name get a suffix: the first 8 hex characters of the SHA-256 of the bundle ID. Two apps called Notes, with the example IDs com.harborlabs.notes and com.fieldkit.notes, become Notes (4e468217).app and Notes (0a0c9bf6).app. The comparison ignores case and accents.

Open the build from Raycast and keep it current

With the shortcut in place, open Raycast and type the app’s name in the main search, like you would for Safari. You’re opening the link, and the link opens the build in your project. The interesting part is what happens next time you build, because that’s where the copy-to-/Applications habit falls apart. App Drawer keeps one app per bundle ID, the newest build, judged by the modification date of its executable or Info.plist. If you build into the same path, the link doesn’t change at all. If a newer build appears somewhere else in the project, the link moves to it.

Run the same build again:

xcodebuild -scheme Marble -configuration Debug -derivedDataPath build build
** BUILD SUCCEEDED **

xcodebuild replaces the app in place, so the path stays the same. App Drawer sees the link already points there and leaves it alone. Raycast opens the new build without anything being written.

Example 2: a Release build moves the shortcut. Now build the Release configuration into the same folder:

xcodebuild -scheme Marble -configuration Release -derivedDataPath build build

That gives you a second Marble.app in build/Build/Products/Release/, with the same bundle ID and a newer date. After the next walk, the link follows it:

readlink ~/Applications/"App Drawer Apps"/Marble.app
/Users/flavio/dev/marble/build/Build/Products/Release/Marble.app

Build Debug again later and the link moves back. If you want Raycast to always open one configuration, delete the other one’s folder under build/Build/Products. One more case: a copy in /Applications or ~/Applications with the same bundle ID joins the race. If it’s newer, the shortcut points at that copy.

To take an app out of Raycast, hide it in App Drawer. Right-click it in the panel and choose Hide from App Drawer, or:

appdrawer hide Marble
Hid Marble (dev.flavio.marble).

The running app removes the link. appdrawer unhide Marble brings the app and its link back. The appdrawer command only changes settings, and App Drawer itself writes the links, so a hide made while App Drawer isn’t running takes effect the next time it starts.

Hand the build command to your coding agent

If a coding agent builds your apps, it probably runs xcodebuild with no -derivedDataPath, and its builds disappear into DerivedData. You test the agent’s work, open Raycast, and get yesterday’s build. Writing the command down once fixes that for every session. I put it in the project’s AGENTS.md, the file agents read before they start. If you haven’t got one, What is an AGENTS.md file explains it. The same command shows up in How to let coding agents test Mac apps in a VM, because a build in a known folder is just as useful there.

A short section is enough:

cat >> AGENTS.md <<'EOF'

## Build

Build with `xcodebuild -scheme Marble -configuration Debug -derivedDataPath build build`.
The app is at `build/Build/Products/Debug/Marble.app`. Don't copy it to /Applications.
EOF

Example 3: the agent got the scheme wrong. An agent typed the scheme by hand and ran:

xcodebuild -scheme Marbel -derivedDataPath build build
xcodebuild: error: The project named "Marble" does not contain a scheme named "Marbel". The "-list" option can be used to find the names of the schemes in the project.

Nothing was built, so the shortcut still points at the last good build, and Raycast happily opens it. That’s the trap: a failed build looks like a build with no visible change. Run xcodebuild -list, copy the scheme name exactly, and put that in AGENTS.md.

If something looks wrong

  • If Raycast opens an old version, run readlink on the shortcut. A path under /Applications means an installed copy with the same bundle ID is newer than your build. Delete that copy or rebuild.
  • If there’s no shortcut for your app, run appdrawer list --filter all. If the app isn’t listed, check appdrawer folders, then press ⌘R in App Drawer to walk the folders again.
  • If the app is listed but has no shortcut, run appdrawer hidden. A hidden app loses its link. appdrawer unhide <app> brings it back.
  • If xcodebuild prints “does not contain a scheme named”, run xcodebuild -list in the project folder and use the name under Schemes.
  • If xcodebuild prints “does not contain an Xcode project, workspace or package”, you’re in the wrong folder. cd into the folder with the .xcodeproj.
  • If the build exists but App Drawer ignores it, check the path. A -derivedDataPath starting with a dot (other than .build), or a folder named old, archive or backup, is skipped, and so is anything deeper than 8 levels in the project.
  • If appdrawer folders add prints appdrawer: Not a folder: ~/Code. Nothing changed., the path doesn’t exist or is a file. Create the folder or fix the typo.
  • If File → Show Raycast Apps Folder shows an error instead of the folder, something else in that folder has the same name as one of your apps. App Drawer never overwrites it. Rename or move that file.

Get App Drawer

Find the Mac apps you build in your project folders and open them from a panel in the Dock. Includes a native Mac app, CLI and full MIT source.

See App Drawer → · Read the docs · $20. See the app page for tax details, with full source code.

More tutorials for my apps →

Want me to talk about your product? You can sponsor this site.