xcbuild

Xcode Build

Build an iOS/macOS app using xcodebuild with automatic project detection and simulator selection.

Arguments

$ARGUMENTS

• No arguments: Use cached settings or prompt for selection on first run
• --change: Clear cached settings and prompt for new scheme and simulator selection
• --scheme=<name>: Use a specific scheme (updates cache)
• --id=<UUID>: Use a specific simulator UUID (one-time, doesn't update cache)

Configuration

Plugin settings are stored in dedicated config files (Claude Code's settings.json has a strict schema):

Scope	File	Use Case
project	.claude/config.json	Team defaults, version controlled
local	.claude/config.local.json	Personal settings, gitignored

Project Settings (.claude/config.json)

Team defaults, committed to version control:

{
  "release-plugin": {
    "xcbuild": {
      "scheme": "MyApp",
      "showWarnings": true
    }
  }
}

Local Settings (.claude/config.local.json)

Personal settings, gitignored (simulator UUIDs are machine-specific):

{
  "release-plugin": {
    "xcbuild": {
      "simulatorId": "A2444326-C93A-4271-9EF0-C44AA5D4FC42",
      "scheme": "MyApp-Dev"
    }
  }
}

Settings Reference

Setting	Recommended Scope	Description
scheme	project	Default scheme (team default)
simulatorId	local	Default simulator UUID (machine-specific)
showWarnings	project	Show build warnings in output (default: true)

Precedence (highest to lowest)

1. Command-line arguments (--scheme=, --id=)
2. Local config (.claude/config.local.json)
3. Project config (.claude/config.json)
4. Session cache
5. Prompt user

Instructions

Step 1: Check for arguments and cached settings

Parse $ARGUMENTS:

• If --id=<UUID> is provided, use that UUID for this build only (skip to Step 5)
• If --scheme=<name> is provided, use that scheme and update cache (proceed to Step 3)
• If --change is provided, clear all cached settings and proceed to Step 1b
• If no arguments, check settings in precedence order:
  1. .claude/config.local.json → release-plugin.xcbuild.scheme and simulatorId
  2. .claude/config.json → release-plugin.xcbuild.scheme and simulatorId
  3. Session cache from earlier in this conversation
  4. If scheme is missing, proceed to Step 1b (detect project, then select scheme)
  5. If simulator is missing, proceed to Step 3 (query and select simulator)
  6. If both are found, skip to Step 5 (run build - trust saved simulator ID)