Driving Xcode from Claude Code

Working model: Claude Code is the editor; Xcode is an attached build/run/debug/docs service. The user is not editing in Xcode — it's open so its services are reachable. Never assume the Xcode UI state (current file, selection) means anything unless asked about it, and remember some calls mutate state the human also sees (run destination, debugger, simulator).

Per-tool verdicts and nuances: references/tool-reference.md.

Session bootstrap (once per session)

1. XcodeListWindows → parse tabIdentifier from the message text; match

on workspacePath if several windows. No workspace open → everything else is unusable; ask the user or open -a Xcode-beta <path>.xcodeproj.

1. Only if you'll build/run: confirm the destination via the

activeDestinationDisplayTitle field of XcodeSwitchScheme/…Destination responses — do NOT call XcodeListRunDestinations (15KB) unless you actually need to change OS/device class.

tabIdentifier is Xcode-side state: survives agent restarts, dies with Xcode. Tools enumerate at agent-session start — if Xcode wasn't running then, the tools are absent until reconnect/restart.

Division of labor — native tools vs xcode-tools vs CLI

The project type matters: in SwiftPM packages (Package.swift), membership IS the folder layout — native file tools do everything, and the Xcode file tools add nothing. In .xcodeproj projects, membership lives in the pbxproj — file lifecycle must go through Xcode tools or the build won't see your changes.

What only this server gives you

1. XcodeRefreshCodeIssuesInFile — live sourcekit diagnostics with no

build, seeing more than the compiler emits. Not instant (~7–10s observed): prefer it when a build is undesirable; on warm small projects an incremental BuildProject is both faster and authoritative.

1. InvokeDebuggerCommand — a real lldb into the running app, sharing

Xcode's debug-console session. Etiquette: the human sees your commands; process interrupt before expressions, continue promptly, remove any breakpoints you set.

1. RenderPreview — compile-and-snapshot any #Preview to a PNG.
2. Membership-aware file ops for .xcodeproj projects.
3. DeviceInteractionSynthesize — taps/swipes/typing + screenshot + UI

hierarchy + app stderr per call, with command chaining (verified live; needs an iOS 27+ simulator runtime — iOS only, Mac refused).

1. Crash/field-performance services — Apple's field data + triage docs,

for apps connected in Organizer (pass bundle_id explicitly; the auto-resolution claim is false in practice).

Verification ladder (cheapest first — but read the timings)

1. BuildProject — authoritative compile+link; self-reports elapsedTime

(0.1s null build, ~4s small warm compile). On warm projects this is usually the cheapest real check.

1. XcodeRefreshCodeIssuesInFile — per-file, no build artifacts, catches

hallucinated APIs and more diagnostics than the compiler (~7–10s). Misses cross-file/link breaks.

1. RunCodeSnippet — behavior probe in project context (~15–25s).
2. RunSomeTests → RunAllTests — highest signal; ~14s with a warm

simulator, 45s+ cold. Once the sim is booted, tests are cheap — use them.

Token cost & noise control

Most responses are pre-quieted summaries; the xcodebuild firehose goes to artifact files (/var/folders/…/T/ActionArtifacts/default/<Tool>/…) — grep those, never read linearly. The exceptions to watch:

Gotcha: GetBuildLog and XcodeListNavigatorIssues default to severity:"error" — a warnings-only build looks empty until you pass severity:"warning".

Failure modes & repair

Setup (one-time):

claude mcp add --scope user xcode-tools \
  --env DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer \
  -- /Applications/Xcode-beta.app/Contents/Developer/usr/bin/mcpbridge