Xcode Workflows

Use the execute_xcode_command MCP tool for all iOS build operations

The xclaude-plugin provides the execute_xcode_command MCP tool which consolidates all xcodebuild operations into a single, token-efficient dispatcher.

⚠️ CRITICAL: Always Use MCP Tools First

This is the most important rule: When working with iOS builds, you MUST use the execute_xcode_command MCP tool.

• ✅ DO: Invoke execute_xcode_command for all build/test/clean operations
• ✅ DO: If the MCP tool fails, adjust parameters and retry
• ✅ DO: Read error messages and debug the parameters
• ❌ NEVER: Fall back to bash xcodebuild commands
• ❌ NEVER: Use xcodebuild directly in bash
• ❌ NEVER: Run xcrun xcodebuild in a terminal

Why? The MCP tool provides:

• Structured error handling
• Token efficiency (consolidated into 1 tool vs. verbose bash output)
• Proper integration with the xclaude-plugin architecture
• Consistent response formatting

If execute_xcode_command fails, the issue is with parameters or the project - not that you should use bash.

When to Use Bash (And When NOT to)

❌ NEVER Use Bash For These (Use MCP Tools Instead)

Task	❌ WRONG (Bash)	✅ RIGHT (MCP Tool)
List schemes	xcodebuild -list	execute_xcode_command op: "list"
Build app	xcodebuild -scheme...	execute_xcode_command op: "build"
Run tests	xcodebuild -scheme... test	execute_xcode_command op: "test"
Clean build	xcodebuild clean	execute_xcode_command op: "clean"
Get Xcode info	xcodebuild -version	execute_xcode_command op: "version"

✅ Bash is Acceptable For (Non-Build Tasks)

• File operations: mkdir, cp, rm, ls, etc.
• Text inspection: grep, find, cat, etc.
• Git operations: git status, git log, etc.
• Environment checks: which, xcode-select --version, etc.
• Project exploration: find . -name "*.swift", etc.

The Rule: If it's about Xcode building/testing → Use MCP tool, not bash

Quick Reference

Task	MCP Tool	Operation	Key Parameters
Build for simulator	execute_xcode_command	build	scheme, configuration:Debug
Build for device	execute_xcode_command	build	scheme, configuration:Release, destination
Run tests	execute_xcode_command	test	scheme, destination
Clean build	execute_xcode_command	clean	scheme
List schemes	execute_xcode_command	list	-
Get Xcode info	execute_xcode_command	version	-

Standard Workflows

1. Building an App

Step 1: Discover Schemes - Use execute_xcode_command with operation: "list"

Invoke the execute_xcode_command MCP tool:

{
  "operation": "list",
  "project_path": "/path/to/Project.xcodeproj"
}

Note: project_path is optional - auto-detected from current directory.

Returns:

{
  "schemes": ["MyApp", "MyAppTests", "MyAppUITests"],
  "targets": ["MyApp", "MyAppKit", "MyAppTests"]
}

Step 2: Build - Use execute_xcode_command with operation: "build"

Invoke the execute_xcode_command MCP tool with build parameters:

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "destination": "platform=iOS Simulator,name=iPhone 15"
}

Common Destinations:

• iOS Simulator: "platform=iOS Simulator,name=iPhone 15"
• iOS Device: "platform=iOS,id=<device-udid>"
• Any Simulator: "platform=iOS Simulator,name=Any iOS Simulator Device"
• macOS: "platform=macOS"

2. Running Tests

Unit Tests:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15"
}

Specific Test Plan:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "test_plan": "UnitTests"
  }
}

Run Specific Tests:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "only_testing": [
      "MyAppTests/LoginTests/testSuccessfulLogin",
      "MyAppTests/LoginTests/testInvalidCredentials"
    ]
  }
}

Skip Specific Tests:

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "skip_testing": [
      "MyAppUITests"
    ]
  }
}

3. Clean Build

When to Clean:

• Build artifacts corrupted
• Switching branches significantly
• Mysterious build failures
• Before release builds

{
  "operation": "clean",
  "scheme": "MyApp"
}

Clean + Build Pattern:

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "options": {
    "clean_before_build": true
  }
}

Configurations

Debug vs Release

Debug (Default):

• Optimizations disabled
• Debug symbols included
• Faster compile time
• Larger binary
• Use for: Development, testing

Release:

• Optimizations enabled
• Debug symbols optional
• Slower compile time
• Smaller binary
• Use for: Production, App Store, performance testing

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Release"
}

Build Options

Common Options

{
  "operation": "build",
  "scheme": "MyApp",
  "options": {
    "clean_before_build": true,
    "parallel": true,
    "sdk": "iphoneos17.0",
    "arch": "arm64",
    "quiet": false
  }
}

Options Explained:

• clean_before_build: Clean before building (ensures fresh build)
• parallel: Enable parallel builds (faster on multi-core)
• sdk: Specific SDK version (usually auto-selected)
• arch: Target architecture (arm64 for devices, x86_64 for old simulators)
• quiet: Reduce build output verbosity

Interpreting Build Results

Success Response

{
  "success": true,
  "summary": "Build succeeded",
  "warnings": 3,
  "build_time": "45.2s",
  "scheme": "MyApp",
  "configuration": "Debug"
}

Failure Response

{
  "success": false,
  "error": "Build failed",
  "errors": 2,
  "warnings": 5,
  "failure_reason": "Compilation errors in ViewController.swift"
}

Progressive Disclosure

Large build logs use progressive disclosure:

{
  "success": true,
  "summary": "Build succeeded with 15 warnings",
  "cache_id": "build-abc123",
  "quick_stats": {
    "warnings": 15,
    "build_time": "62.3s"
  },
  "next_steps": [
    "Use cache_id to get full build log if needed",
    "Review warnings for potential issues"
  ]
}

Common Build Errors

Error: "No scheme named 'X' found"

Cause: Scheme doesn't exist or isn't shared

Solution:

1. Run list operation to see available schemes
2. Check if scheme is shared (Xcode → Product → Scheme → Manage Schemes)

Error: "Code signing identity not found"

Cause: Missing or invalid signing certificate

Solution:

1. Check Team ID in project settings
2. Verify certificates in Keychain
3. Use automatic signing if possible

{
  "operation": "build",
  "scheme": "MyApp",
  "options": {
    "code_sign_identity": "Apple Development",
    "development_team": "TEAM_ID_HERE"
  }
}

Error: "SDK not found"

Cause: Requesting unavailable SDK version

Solution:

1. Run version operation to see available SDKs
2. Update sdk option or remove to use latest

Error: "Destination not found"

Cause: Invalid destination specifier

Solution:

1. Use execute_simulator_command with operation "list" to see available devices
2. Check device name spelling
3. Ensure device/simulator is available

Testing Workflows

Complete Test Suite

1. list → Get test scheme
2. clean → Ensure fresh state
3. test → Run all tests
4. Analyze results → Check for failures

Flaky Test Detection

Run tests multiple times:

{
  "operation": "test",
  "scheme": "MyApp",
  "options": {
    "test_iterations": 5,
    "retry_on_failure": true
  }
}

Note: Test iteration support depends on Xcode version.

Test Result Analysis

Tests return:

{
  "success": false,
  "tests_run": 45,
  "tests_passed": 43,
  "tests_failed": 2,
  "failures": [
    {
      "test": "MyAppTests.LoginTests.testInvalidPassword",
      "message": "XCTAssertEqual failed: (\"error\") is not equal to (\"invalid\")"
    }
  ]
}

Project Auto-Detection

xcodebuild operations auto-detect project files:

1. Searches current directory for .xcworkspace
2. Falls back to .xcodeproj
3. Returns error if multiple or none found

Explicit Path:

{
  "operation": "build",
  "project_path": "/path/to/specific/Project.xcodeproj",
  "scheme": "MyApp"
}

Build Performance Tips

1. Enable Parallel Builds

{
  "options": {
    "parallel": true
  }
}

2. Incremental Builds

Don't clean unless necessary - incremental builds are much faster.

3. Reduce Verbosity

For CI/automated builds:

{
  "options": {
    "quiet": true
  }
}

4. Use Derived Data Caching

Default behavior - xcodebuild uses DerivedData for caching.

CI/CD Integration

GitHub Actions Pattern

1. version → Verify Xcode installation
2. list → Validate scheme exists
3. clean → Ensure fresh build
4. build → Compile project
5. test → Run test suite
6. Analyze results → Fail pipeline if tests fail

Build Artifacts

Build produces:

• .app bundle in DerivedData
• .xcresult test results bundle
• Build logs (via progressive disclosure)

Advanced: Build Settings

Query build settings:

{
  "operation": "list",
  "project_path": "/path/to/Project.xcodeproj"
}

Returns scheme/target info. For detailed build settings, use Resource:

xc://reference/build-settings

Scheme Management

Shared vs User Schemes

Shared Schemes:

• Checked into source control
• Available to all users
• Recommended for team projects

User Schemes:

• Local to your machine
• Not visible to xcodebuild by default

Best Practice: Share schemes used for CI/CD.

Integration with MCP Tools

This Skill works with execute_xcode_command tool:

• All operations use the execute_xcode_command tool
• Tool handles xcodebuild execution and output parsing
• Tool provides progressive disclosure for large outputs
• This Skill teaches WHEN and HOW to use operations

Related Skills

• ios-testing-patterns: Advanced test strategies and analysis
• simulator-workflows: Device management for testing
• crash-debugging: Analyzing build crashes

Related Resources

• xc://operations/xcode: Complete xcodebuild operations reference
• xc://reference/build-settings: Build settings dictionary
• xc://reference/error-codes: Common error codes and solutions

---

Tip: Use list to discover, build to compile, test to validate. Clean only when needed.