Switching Xcode Scheme

Switching Xcode Scheme

Overview

The Xcode MCP tools (BuildProject, RunSomeTests, RunAllTests) always act on the active scheme and active destination of the focused Xcode workspace. They take no scheme or destination arguments. To build a different target or run on a different simulator, you must change Xcode's selection first.

This skill wraps an AppleScript helper that:

• Sets the active scheme of the workspace document Xcode currently has focused (works reliably; verified by read-after-write).
• Lists schemes and run destinations for that workspace, with optional substring filtering.
• Cannot change the active run destination — see the limitation section below.

When to use

• Before calling Xcode MCP BuildProject / RunSomeTests / RunAllTests tools and the active scheme isn't the target you want.
• The user asks to "build/test/run scheme X" and you don't know whether X is currently selected.
• The user asks "what schemes are in this project?" or "what simulators can I run on?" and you want a definitive list straight from Xcode (rather than parsing project files).

When NOT to use

• Xcode is not running, or no workspace/project is open. The script will fail with a clear message — don't use it as a way to launch Xcode.
• You need to switch the active run destination (simulator/device). AppleScript silently no-ops on Xcode 26.x. Ask the user to pick the destination in Xcode's toolbar instead.
• You're working with xcodebuild (CLI) rather than driving the Xcode app. xcodebuild takes -scheme and -destination flags directly — this skill is for the IDE, not the CLI.

Quick reference

The helper lives at xcode-state.sh in this skill's directory. Run it directly via its absolute path.

Run with no arguments or help to print full usage. Exit code 1 means Xcode is not running / no workspace open / item not found; exit code 2 means usage error.

The scheme <name> for scheme <name> must match exactly (use the listing command first if unsure). Destination names already include the OS version in parens, e.g. iPhone 17 Pro (26.4.1).

The run destination limitation

Xcode's AppleScript dictionary defines active run destination as a settable property of the workspace document. In Xcode 26.x this property is broken in both directions:

• Reads always return missing value, even immediately after a successful set and even when Xcode visibly has a destination selected.
• Writes don't error, but the underlying xcuserstate doesn't update and there's no observable change in subsequent Xcode behavior.

UI scripting via System Events can drive Xcode's toolbar dropdown, but it requires the invoker to have Accessibility permission, which Claude Code typically doesn't have. So this skill doesn't attempt destination writes. If destination switching is essential, ask the user to change it in the Xcode toolbar before running an MCP build.

Common mistakes

• Forgetting that scheme set is a precondition for the Xcode MCP tools. If you call BuildProject without first switching scheme, it builds whatever was selected — possibly not what the user asked for. Read the current scheme first if you're unsure.
• Passing a substring to scheme <name>. That command requires an exact match. For substring search, use schemes <pattern> to find the full name first.
• Treating "set destination" as a no-op safely. The AppleScript set will not error, but the destination will not change. Don't claim success based on the absence of an error.
• Operating on the wrong workspace. The helper always targets active workspace document. If the user has multiple Xcode windows open, confirm with xcode-state.sh workspace before switching schemes.