
release
Xcode release automation for Claude Code: SemVer bumps and tags, changelogs, decisions tracking and TestFlight notes for iOS/macOS apps
- version
- 1.3.4
- GitHub stars
- 10
Install
/plugin install release@scarrillo-releaseRun it inside Claude Code after adding the marketplace with /plugin marketplace add scarrillo/release.
Contents
Discovered from sourceCommands 5
Changelog Generator
Generate a comprehensive changelog document based on recent changes in this project.
Model Selection
Before generating the changelog, check for model preference:
-
Check config for
release-plugin.modelsetting -
If not set, ask the user: "Which model should I use for changelog generation?"
- Current model (inherit from conversation)
- Claude Opus 4.5 (
claude-opus-4-5-20251101) - Most capable - Claude Sonnet 4 (
claude-sonnet-4-20250514) - Balanced (Recommended) - Claude Haiku 3.5 (
claude-3-5-haiku-20241022) - Fastest
Then ask: "Save this as default for this project?"
- If yes, persist to
.claude/config.jsonunderrelease-plugin.model
Note: Model selection applies to all plugin commands (changelog, decisions, whattotest).
Instructions
-
Analyze recent changes using this priority order:
Primary source - Current session:
- Review all work completed in this conversation session
- Include files created, modified, features implemented, and bugs fixed
- This is the most accurate and detailed source of recent work
Cross-reference with git to deduplicate:
- Check recent git commit history (
git log) - Check staged changes (
git diff --staged) - Check unstaged changes (
git diff) - Use git data to verify session work and avoid duplicate entries
- If work from the session has already been committed, use the commit info to enrich the changelog entry (commit hash, timestamp)
Handle uncommitted session work:
- If session work is not yet committed, ask the user:
- "Commit first" - Let the user commit their changes, then proceed
- "Include uncommitted" - Generate changelog including uncommitted session work
- "Skip uncommitted" - Only include work that has been committed
Reference existing changelogs:
- Check any existing changelog files for format consistency and to avoid re-documenting old changes
-
Categorize changes into:
- Features: New functionality added
- Improvements: Enhancements to existing features
- Bug Fixes: Issues that were resolved
- Breaking Changes: Changes that may affect existing functionality (if any)
-
Generate two summaries (in this order):
Internal Developer Summary (write this first)
Create comprehensive technical notes for the development team using Problem/Solution format. This is the authoritative record of all changes.
For each change, include:
- Problem: What issue or need prompted this change?
- Solution: How was it solved? Include relevant code snippets.
- How It Works: For complex features, explain the implementation logic
- Files Changed: List of files modified/created with brief description of each
- Dependencies: Any packages added/updated
- Migration Notes: Steps needed if applicable
- Known Issues: Any limitations or issues to be aware of
Public User-Facing Summary (derive from developer summary)
Based on the Internal Developer Summary above, create a simplified user-friendly version:
- Translate technical features into user benefits
- Rewrite improvements in plain, non-technical language
- Describe bug fixes by the problem they solve (not the technical fix)
- Omit: Internal refactoring, technical debt, developer tooling changes, implementation details users don't need to know
Output Location
Two files are generated:
changelog.md- Internal Developer Summary (comprehensive technical notes)changelog-public.md- Public User-Facing Summary (user-friendly release notes)
Both files are created in the same location.
If changelog.md doesn't exist, ask the user: "Where should I create the changelog files?"
- Project root (
./changelog.mdand./changelog-public.md) - Documentation folder (
./docs/changelog.mdand./docs/changelog-public.md) - Custom location (let user specify)
If changelog.md already exists, use its current location for both files.
If files exist: Prepend new entries after the header (newest entries at top). Read existing content first to avoid duplicates and maintain format consistency.
Output Format
changelog.md (Internal Developer Summary)
# Changelog
## [Version] - YYYY-MM-DD
#### [Feature/Fix Name]
**Problem**: [Description of the issue or need]
**Solution**: [How it was solved]
```swift
// Relevant code snippet showing the implementation
How It Works: [For complex features, explain the logic]
Files Changed:
path/to/file.swift- [what changed]path/to/another.swift- [what changed]
Dependencies: [Any added/updated, or "None"]
Known Issues: [Any limitations, or "None"]
### changelog-public.md (Public User-Facing Summary)
```markdown
# Release Notes
## [Version] - YYYY-MM-DD
### What's New
- [User-friendly feature description]
### Improvements
- [User-friendly improvement description]
### Bug Fixes
- [User-friendly fix description]
---
After Changelog Generation
Once the changelog is complete, ask the user about follow-up documentation:
-
Decisions: "Were there any decisions or proposals discussed this session that should be documented?"
- If yes, run /decisions to capture decisions, proposals, and trade-offs from the session
- This includes implemented decisions, deferred ideas, and rejected approaches
-
WhatToTest (Xcode projects only):
- Check config for
release-plugin.whattotest.enabledsetting - If not set, detect if this is an Xcode project by checking for:
.xcodeproj,.xcworkspace,Package.swift, orPodfile - If Xcode project detected (or
enabled: truein config):- Ask: "Would you like me to generate TestFlight WhatToTest from the public-facing summary?"
- Offer to save preference: "Save this as default for this project?"
- If not an Xcode project (and no config override), skip this prompt
- If yes, use the Public User-Facing Summary to generate WhatToTest.en-US.txt
- Do not re-analyze - derive directly from the public summary
- Check config for
Arguments
$ARGUMENTS
Version/date range: Scope changelog to specific version or time period
/release:changelog v1.2.0/release:changelog 2024-01-01
Follow-up behavior flags:
--auto- Automatically run both /decisions and /whattotest without asking--ask- Ask before running each follow-up (default)--skip- Skip all follow-ups, only generate changelog--decisions- Auto-run /decisions only--whattotest- Auto-run /whattotest only--no-decisions- Skip /decisions prompt--no-whattotest- Skip /whattotest prompt
Examples:
/release:changelog --auto- Generate all docs without prompts/release:changelog --skip- Only changelog, no follow-ups/release:changelog v1.2.0 --decisions --no-whattotest- Version 1.2.0, auto-run decisions, skip whattotest
Configuration File
Check for .claude/config.json at project root. Look for settings under the release-plugin namespace:
{
"release-plugin": {
"model": "claude-sonnet-4-20250514",
"changelog": {
"outputPath": "./changelog.md",
"followUp": {
"decisions": "ask",
"whattotest": "ask"
}
},
"decisions": {
"outputPath": "./decisions.md"
},
"whattotest": {
"onExisting": "ask"
}
}
}
Config Options
release-plugin.model: Model for all plugin commands
"inherit"- Use current conversation model (default)"claude-opus-4-5-20251101"- Most capable"claude-sonnet-4-20250514"- Balanced (recommended)"claude-3-5-haiku-20241022"- Fastest
release-plugin.changelog.outputPath: "./changelog.md" | "./docs/changelog.md" | custom path
release-plugin.changelog.followUp.decisions: "always" | "ask" | "never"
release-plugin.changelog.followUp.whattotest: "always" | "ask" | "never"
release-plugin.decisions.outputPath: "./decisions.md" | "./docs/decisions.md" | custom path
release-plugin.whattotest.enabled: "auto" (detect Xcode project) | true | false
release-plugin.whattotest.outputPath: "./TestFlight/WhatToTest.en-US.txt" | custom path
release-plugin.whattotest.onExisting: "prepend" | "replace" | "ask"
Persisting User Choices
When prompting the user for a location or preference, offer to save their choice:
"Would you like to save this preference to .claude/config.json for future runs?"
If yes:
- Check if
.claude/config.jsonexists in the project root - If not, create the
.claude/directory andconfig.jsonfile - Read existing config (if any) to preserve other settings
- Add/update the setting under the
release-pluginnamespace - Write the updated config back to the file
Example - saving changelog outputPath:
# Create .claude directory if needed
mkdir -p .claude
# Write config with the user's preference
{
"release-plugin": {
"changelog": {
"outputPath": "./docs/changelog.md"
}
}
}
Command-line arguments override config file settings.
Decisions Document Generator
Capture decisions and proposals from the current session for future reference. Includes both implemented decisions and proposals still under consideration.
Model: Uses the model configured in release-plugin.model (see /release:changelog for model selection).
How to Run
- Standalone: Run
/decisionsdirectly at any point to capture decisions from the current session - From /release:changelog: After generating a changelog, you'll be prompted to run this command
When to Use
- After discussing architectural approaches
- When a decision was made (implemented or not)
- When proposals were explored but deferred
- After comparing solutions or libraries
- When trade-offs were evaluated
- After a research or exploration session (even without code changes)
Instructions
-
Review current session for:
- Decisions made (with rationale)
- Proposals discussed (implemented or not)
- Approaches compared
- Trade-offs evaluated
- Ideas deferred for later
-
Capture regardless of implementation status:
- Implemented → document the decision and link to changelog
- Not implemented → document as proposal for future review
- Rejected → document why it was rejected (valuable context)
-
Organize by topic for easy future reference
Output Location
If decisions.md doesn't exist, ask the user: "Where should I create the decisions document?"
- Project root (
./decisions.md) - Documentation folder (
./docs/decisions.md) - Same location as changelog (if it exists)
- Custom location (let user specify)
If decisions.md already exists, use its current location.
If file exists: Prepend new entries after the # Decisions & Proposals header (newest entries at top). Read existing content first to avoid duplicates.
Output Format
Structure:
# Decisions & Proposals
## [Topic/Feature Area] - YYYY-MM-DD
### Status: [Implemented | Proposed | Rejected | Deferred]
### Context
[What problem or question prompted this decision/proposal?]
### Proposal
[What was proposed or decided?]
### Options Considered
1. **[Option A]**: [Brief description]
- Pros: [advantages]
- Cons: [disadvantages]
2. **[Option B]**: [Brief description]
- Pros: [advantages]
- Cons: [disadvantages]
### Decision
[What was decided, or "Pending review" if still a proposal]
### Rationale
[Why this approach was chosen/proposed]
### Trade-offs Accepted
[What compromises come with this decision]
### References
- [Links to docs, samples, related PRs]
---
Status Definitions
- Implemented: Decision was made and code was written (see changelog)
- Proposed: Idea discussed, not yet implemented, worth revisiting
- Deferred: Good idea, but intentionally postponed
- Rejected: Considered and decided against (document why)
Arguments
If a specific topic is provided, scope to that area: $ARGUMENTS
Release Version Manager
Interactive version management for software projects. Automates semantic versioning (SemVer), project file updates, and git tag creation.
Model: Uses the model configured in release-plugin.model (see /release:changelog for model selection).
Instructions
1. Detect Project Type
Check for project files in the project root only (not recursively) in this order:
| Project Type | Detection | Version File(s) |
|---|---|---|
| Claude Plugin | .claude-plugin/plugin.json in project root | plugin.json + marketplace.json → version |
| Xcode (iOS/macOS) | *.xcodeproj directory in project root | project.pbxproj → MARKETING_VERSION |
| (Future: Next.js) | package.json + next.config.* | package.json → version |
| (Future: Android) | build.gradle or build.gradle.kts | build.gradle → versionName |
Important: Only check the immediate project root for detection files. Do not search subdirectories to avoid finding installed plugins, dependencies, or nested projects.
If no supported project type found: "No supported project detected. Currently supports: Claude Plugin, Xcode (iOS/macOS)"
2. Read Current Version
For Claude plugins:
- Read
.claude-plugin/plugin.json - Extract
versionfield value - Parse SemVer components (MAJOR.MINOR.PATCH)
Display: "Project: Claude Plugin ([plugin name])" Display: "Current version: X.Y.Z"
For Xcode projects:
- Find
.xcodeprojdirectory in project root - Read
<project>.xcodeproj/project.pbxproj - Extract first
MARKETING_VERSION = X.Y.Z;value - Parse SemVer components (MAJOR.MINOR.PATCH)
Display: "Project: [ProjectName].xcodeproj" Display: "Current version: X.Y.Z"
3. Prompt for Increment Type
If no argument provided, ask the user:
"Select version increment (SemVer):"
| Option | Result | Description |
|---|---|---|
| 1. patch | X.Y.(Z+1) | Bug fixes, backwards compatible |
| 2. minor | X.(Y+1).0 | New features, backwards compatible |
| 3. major | (X+1).0.0 | Breaking changes |
| 4. tag | (no change) | Create or update tag only |
4. Generate Release Documentation (Optional)
Before committing the release, ask the user:
"Would you like to generate release documentation first?"
- Yes - Run
/release:changelognow (recommended) - No - Skip documentation
If yes, execute /release:changelog which will:
- Generate
changelog.md(developer notes) - Generate
changelog-public.md(user-facing release notes) - Optionally prompt for
/release:decisionsand/release:whattotest
This ensures documentation is included in the release commit.
5. Check Git Execution Mode
Check config for release-plugin.release.gitMode setting.
If not set, ask the user:
"How should git commands be handled?"
- Run automatically - Claude executes git commands (showing progress)
- Show commands only - Display commands for you to run manually
If user selects option 1 (auto):
- Confirm Claude has permission to execute git commands
- Request bash permissions for git operations if needed
- Test with a safe command like
git statusto verify access
Then ask: "Save this preference for future runs?"
- If yes, persist to
.claude/config.jsonunderrelease-plugin.release.gitMode- Option 1 →
"auto" - Option 2 →
"manual"
- Option 1 →
6. Execute Version Increment
For patch/minor/major:
-
Calculate new version per SemVer:
- patch:
MAJOR.MINOR.(PATCH+1) - minor:
MAJOR.(MINOR+1).0 - major:
(MAJOR+1).0.0
- patch:
-
Show: "New version: X.Y.Z → A.B.C"
-
Confirm: "Proceed with version increment?"
-
Update version file(s):
- Claude Plugin: Update
versionfield in both:.claude-plugin/plugin.json.claude-plugin/marketplace.json(in theplugins[0].versionfield)
- Xcode: Replace ALL
MARKETING_VERSION = X.Y.Z;withMARKETING_VERSION = A.B.C;inproject.pbxproj
- Claude Plugin: Update
-
Verify update succeeded by reading back the version
-
If gitMode is "auto" - Execute git commands (showing each command as it runs):
Running: git add <version-file(s)> # plugin.json + marketplace.json for Claude, or project.pbxproj for Xcode Running: git add <changelog-files> # if documentation was generated Running: git commit -m "Release vA.B.C" Running: git tag rel.vA.B.CThen display:
Done! Version incremented to A.B.C Committed and tagged as 'rel.vA.B.C' To push to remote: git push && git push origin rel.vA.B.C -
If gitMode is "manual" - Display commands for user to run:
Version file updated to A.B.C Run these commands to complete the release: git add <version-file> <changelog-files> git commit -m "Release vA.B.C" git tag rel.vA.B.C git push && git push origin rel.vA.B.C
For tag (create or update tag):
-
Determine tag name:
rel.vX.Y.Z(current version) -
Check if tag exists:
git tag -l rel.vX.Y.Z -
If gitMode is "auto":
- If tag exists:
- Show: "Tag 'rel.vX.Y.Z' exists. Update to current commit?"
- If confirmed, run:
git tag -f rel.vX.Y.Z
- If tag doesn't exist:
- Show: "Create tag 'rel.vX.Y.Z'?"
- If confirmed, run:
git tag rel.vX.Y.Z
- Display success and push command
- If tag exists:
-
If gitMode is "manual":
- If tag exists:
- Display:
git tag -f rel.vX.Y.Zandgit push origin -f rel.vX.Y.Z
- Display:
- If tag doesn't exist:
- Display:
git tag rel.vX.Y.Zandgit push origin rel.vX.Y.Z
- Display:
- If tag exists:
Arguments
$ARGUMENTS
Direct increment type:
/release:release patch- Increment patch version (bug fixes)/release:release minor- Increment minor version (new features)/release:release major- Increment major version (breaking changes)/release:release tag- Create or update tag (no version change)
If no argument, show interactive menu.
Configuration
Check for .claude/config.json at project root. Look for settings under release-plugin.release:
{
"release-plugin": {
"release": {
"gitMode": "auto"
}
}
}
| Option | Values | Description |
|---|---|---|
gitMode | "auto" | Claude executes git commands automatically |
"manual" | Claude displays commands for user to run |
The tag Option and CI/CD Triggers
The tag option is useful for triggering CI builds without incrementing the version:
Xcode Cloud workflow:
- Configure Xcode Cloud to build on tags matching
rel.v* - Use
tagto iterate on a release candidate - Force-push updated tag to trigger new build
Example:
# Initial release
/release:release patch # Creates rel.v1.2.4, commits, tags
# Quick fix needed in same version
git commit -m "Fix critical bug"
/release:release tag # Updates rel.v1.2.4 to current commit
git push origin -f rel.v1.2.4 # Triggers new CI build
Project-Specific Notes
Claude Plugin
- Updates version in both
plugin.jsonandmarketplace.json - Both files must have matching versions for marketplace distribution
- Detection is scoped to
.claude-plugin/in project root only
Xcode (iOS/macOS)
- Only modifies
MARKETING_VERSIONin project.pbxproj BUILD_NUMBERis typically auto-incremented by Xcode Cloud- Supports projects with multiple targets (updates all occurrences)
Future Project Types
This command is designed to support additional project types:
- Next.js: Update
versioninpackage.json - Android: Update
versionNameinbuild.gradle - Flutter: Update
versioninpubspec.yaml - React Native: Update both
package.jsonand native projects
Contributions welcome for additional project type support.
TestFlight WhatToTest Generator
Generate a WhatToTest document for TestFlight beta releases.
Model: Uses the model configured in release-plugin.model (see /release:changelog for model selection).
Instructions
-
Locate source content (in priority order):
- If called from /release:changelog: Use the
changelog-public.mdthat was just generated in this session. Do not re-analyze - derive directly from that file. - If called directly: Look for source content in this order:
changelog-public.mdin the project- Recent changelog files in the project
- Git commit history for recent changes
- Release notes or version documentation
- If called from /release:changelog: Use the
-
Check for existing WhatToTest files:
Search for existing WhatToTest files in
./TestFlight/, checking in this order:WhatToTest.en-US.txt(default)- Other locale variants (e.g.,
.de.txt,.fr.txt)
If existing file(s) found, use the same location and filename.
Check config for
release-plugin.whattotest.onExisting:- If
"prepend": Prepend new entry without asking - If
"replace": Replace content without asking - If
"ask"(default): Prompt the user: "WhatToTest file already exists. How should I handle it?"- Prepend new entry (keep history, newest at top) - Recommended
- Replace all (start fresh with only this release)
If no existing file found, create
./TestFlight/WhatToTest.en-US.txt. Create theTestFlight/folder if it doesn't exist. -
Generate WhatToTest content that is:
- Under 4000 characters total (hard limit — TestFlight rejects content exceeding this). Count characters before writing the file. If over, condense until it fits.
- No special characters — use only plain ASCII. Avoid smart quotes, em dashes, bullets (•), or other unicode characters. Use hyphens (-) for lists and straight quotes.
- Concise and actionable for testers
- Focused on what testers should specifically test
- Written in plain language (non-technical)
- Organized by feature area or priority
Output Format
Structure for each release entry:
[App Name] v[Version] - YYYY-MM-DD
[Brief overview of this beta release - 1-2 sentences]
Key Areas to Test:
1. [Feature/Area Name]
- [Specific test case or scenario]
- [Another test case]
2. [Feature/Area Name]
- [Specific test case or scenario]
- [Another test case]
Known Issues:
- [Any known issues testers should be aware of]
Feedback Focus:
- [Specific questions or areas where you want tester feedback]
---
When prepending, each release gets its own section separated by ---.
Notes
- The WhatToTest file is automatically included with your TestFlight build when placed in a
TestFlightfolder at your project root - Keep content under 4000 characters (TestFlight limit)
- Focus on NEW or CHANGED functionality that needs testing
- Localized filenames:
WhatToTest.en-US.txt(US English),WhatToTest.de.txt(German), etc.
Arguments
If a version number is provided, generate WhatToTest content for that specific version: $ARGUMENTS
Xcode Build
Build an iOS app for the iOS Simulator 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)
- Command-line arguments (
--scheme=,--id=) - Local config (
.claude/config.local.json) - Project config (
.claude/config.json) - Session cache
- 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
--changeis provided, clear all cached settings and proceed to Step 1b - If no arguments, check settings in precedence order:
.claude/config.local.json→release-plugin.xcbuild.schemeandsimulatorId.claude/config.json→release-plugin.xcbuild.schemeandsimulatorId- Session cache from earlier in this conversation
- If scheme is missing, proceed to Step 1b (detect project, then select scheme)
- If simulator is missing, proceed to Step 3 (query and select simulator)
- If both are found, skip to Step 5 (run build - trust saved simulator ID)
Step 1b: Detect Xcode project (if needed)
Find the project or workspace in the current directory:
ls -d *.xcworkspace 2>/dev/null || ls -d *.xcodeproj 2>/dev/null
- Prefer
.xcworkspaceover.xcodeproj(workspaces handle CocoaPods/SPM dependencies) - If multiple found, use the first one
- Cache the project/workspace name for subsequent builds
Step 2: Select scheme (if needed)
Get available schemes:
xcodebuild -list -json
Parse the JSON project.schemes array. Identify a recommended scheme:
- Prefer scheme matching the project/workspace name exactly
- Exclude schemes containing "Tests", "UITests", "Keyboard", "Widget", "Extension"
- If only one non-test/extension scheme exists, use it directly without prompting
If multiple schemes are available, use AskUserQuestion:
Header: "Scheme"
Question: "Which scheme should be used for builds?"
Options (show up to 4, add "(Recommended)" suffix to first):
- Main app scheme - description: "Main app target"
- Other schemes with descriptive labels based on name (e.g., "ASC" → "App Store Connect", "Keyboard" → "Keyboard extension only")
Example for a project with schemes ["MyApp", "MyApp ASC Sub", "MyAppKeyboard"]:
- Option 1: "MyApp (Recommended)" - "Main app target"
- Option 2: "MyApp ASC Sub" - "App Store Connect submission"
- Option 3: "MyAppKeyboard" - "Keyboard extension only"
After user selects:
- Cache the scheme name for subsequent builds in this session
- Ask: "Save this scheme as the project default?" (saves to
.claude/config.json)
Step 3: Query available simulators (only when needed)
Only run this step when:
- No simulator ID is configured (first run)
--changeflag was used- Build failed due to invalid simulator
First, output a message to the user: "Querying available simulators..."
Then run this command to get available simulators:
xcrun simctl list devices available --json
Parse the JSON to build a list of available iPhone simulators:
- Group by iOS version (runtime)
- Include device name and UUID
- Sort by iOS version (newest first), then by device name
Identify the recommended simulator: The newest iPhone Pro model on the highest iOS version.
Step 4: Select simulator (first run or after build failure)
Only run this step when:
- No simulator ID is configured (first run)
--changeflag was used- Build failed due to invalid simulator (see Step 5)
Use AskUserQuestion to present options:
Header: "Simulator"
Question: "Which iOS Simulator should be used for builds?"
Options (show up to 4):
- Recommended - e.g., "iPhone 17 Pro Max (iOS 26.2)" with description "Recommended - Latest Pro model"
- Next best option - e.g., "iPhone 17 Pro (iOS 26.2)"
- Another popular option - e.g., "iPhone 16 Pro (iOS 18.2)"
- If user needs something else, they can select "Other" and provide a UUID
After user selects:
- Cache the simulator name and UUID for subsequent builds in this session
- Ask: "Save this simulator for this project?" (saves to
.claude/config.local.json)
Step 5: Run the build
For a workspace:
xcodebuild -workspace <Name>.xcworkspace -scheme <Scheme> -destination "id=<UUID>" build 2>&1 | grep -E "(warning:|error:|BUILD SUCCEEDED|BUILD FAILED)" | grep -v "export " | tail -20
For a project (no workspace):
xcodebuild -project <Name>.xcodeproj -scheme <Scheme> -destination "id=<UUID>" build 2>&1 | grep -E "(warning:|error:|BUILD SUCCEEDED|BUILD FAILED)" | grep -v "export " | tail -20
Note: If release-plugin.xcbuild.showWarnings is false in config, exclude warning: from the grep pattern.
If build fails due to invalid simulator (error contains "unable to find a destination matching" or similar):
- Inform the user: "Configured simulator not found. It may have been deleted or this config is from a different machine."
- Go to Step 3 (query available simulators)
- Then Step 4 (prompt user to select a new simulator)
- Retry the build with the new simulator
Step 6: Report results
Format output as:
Project: <Project/Workspace Name>
Scheme: <Scheme Name>
Simulator: <Device Name> (<iOS Version>)
ID: <UUID>
[Any SwiftLint warnings or build errors]
BUILD SUCCEEDED [X.X sec]
Or on failure:
Project: <Project/Workspace Name>
Scheme: <Scheme Name>
Simulator: <Device Name> (<iOS Version>)
ID: <UUID>
[Build errors]
BUILD FAILED - [summary of errors]
Persisting User Choices
After selecting scheme or simulator, offer to save:
For scheme (team default): "Save this scheme as the project default?"
- If yes, save to
.claude/config.jsonunderrelease-plugin.xcbuild.scheme - This is version controlled and shared with the team
For simulator (personal/machine-specific): "Save this simulator for this project?"
- If yes, save to
.claude/config.local.jsonunderrelease-plugin.xcbuild.simulatorId - This is gitignored (machine-specific UUIDs)
Saving to a config file
- Create
.claude/directory if needed - Read existing file content (if any) to preserve other settings
- Parse as JSON, or start with empty object
{} - Ensure
release-plugin.xcbuildpath exists - Add/update the specific setting
- Write the updated JSON back to the file
- Create parent directories if needed (e.g.,
mkdir -p ~/.claude)
Examples
First run (no cached settings):
/release:xcbuild
→ Detects project, asks user to select scheme and simulator, caches choices, runs build
Subsequent runs:
/release:xcbuild
→ Uses cached project/scheme/simulator, runs build immediately
Change scheme and simulator:
/release:xcbuild --change
→ Clears cache, asks user to select new scheme and simulator, updates cache, runs build
Use specific scheme:
/release:xcbuild --scheme=FontPopKeyboard
→ Uses specified scheme, updates cache, uses cached simulator
Use specific simulator UUID:
/release:xcbuild --id=A2444326-C93A-4271-9EF0-C44AA5D4FC42
→ Uses provided UUID for this build only (doesn't update cache)
Sponsors
Details
- Marketplace
- scarrillo/release
- Author
- Shawn Carrillo
- Category
- Productivity
- License
- MIT
- Keywords
- release, release-automation, semver, semantic-versioning, versioning, changelog, release-notes, git, git-tag, ci-cd, cicd, testflight, whattotest, ios, macos, xcode, adr, decisions, documentation, automation