Make Raycast find the Mac apps you build in Xcode
By Flavio
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:
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
readlinkon the shortcut. A path under/Applicationsmeans 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, checkappdrawer folders, then press⌘Rin 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
xcodebuildprints “does not contain a scheme named”, runxcodebuild -listin the project folder and use the name under Schemes. - If
xcodebuildprints “does not contain an Xcode project, workspace or package”, you’re in the wrong folder.cdinto the folder with the.xcodeproj. - If the build exists but App Drawer ignores it, check the path. A
-derivedDataPathstarting with a dot (other than.build), or a folder namedold,archiveorbackup, is skipped, and so is anything deeper than 8 levels in the project. - If
appdrawer folders addprintsappdrawer: 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.
Want me to talk about your product? You can sponsor this site.