Xcode Release Automation for Claude Code

Release your iOS and macOS apps from Claude Code: bump the version, tag, write the changelog and TestFlight notes, and build for the iOS Simulator, in a few commands. Also releases Claude Code plugins.

Why Use This?

Shipping an iOS/macOS build is the same chore every time. This plugin automates the repetitive parts:

• Version Management - Increment versions per SemVer, commit, and tag in one command
• Changelogs - Problem/Solution format from your session, not vague commit messages
• Decisions - Capture the "why" behind choices, even ones you didn't implement
• TestFlight notes - Beta tester instructions derived directly from your changelog

Requirements

• Claude Code CLI
• An Xcode project (iOS/macOS), or a Claude Code plugin

Installation

Install from the scarrillo marketplace, which also carries my other Claude Code plugins:

# Add the marketplace
/plugin marketplace add scarrillo/agent-plugins

# Install the plugin
/plugin install release@scarrillo

Or add this repo on its own, as its own marketplace:

/plugin marketplace add scarrillo/release
/plugin install release@scarrillo-release

Install from one marketplace or the other, not both, or the plugin loads twice.

Commands

Note: Commands are namespaced with release: prefix when installed via marketplace.

Workflow

/release:changelog       # Document completed work
         ↓
/release:decisions       # Capture decisions (prompted)
         ↓
/release:whattotest      # Generate test notes (prompted)
         ↓
/release:release         # Increment version, commit, tag

Or run any command standalone.

Features

/release:release

• Increment version per SemVer (major, minor, patch)
• Auto-detects project type: Claude Plugin, Xcode (more platforms coming)
• Prompts to generate changelog before committing
• Updates version file(s), commits, and creates git tag
• tag option for CI/CD triggers without version change

/release:changelog

• Uses current session context as primary source
• Cross-references with git to deduplicate
• Problem/Solution format with code snippets
• Generates two files:
  • changelog.md - Technical developer notes
  • changelog-public.md - User-friendly release notes

/release:decisions

• Documents decisions regardless of implementation status
• Tracks: Implemented, Proposed, Deferred, Rejected
• Records rationale and trade-offs

/release:whattotest

• Derives content from changelog-public.md
• Creates TestFlight/ folder structure
• Tester-focused, actionable format
• Stays within 4000 character limit

/release:xcbuild

• Auto-detects .xcworkspace or .xcodeproj in current directory
• Lists available schemes and recommends main app target
• Queries available simulators and recommends latest iPhone Pro
• Caches selections for fast subsequent builds
• Persists settings to plugin config files:
  • Scheme → .claude/config.json (project/team default)
  • Simulator → .claude/config.local.json (gitignored, machine-specific)
• Arguments: --change (re-select), --scheme=<name>, --id=<UUID>

Supported Project Types

More platforms coming: Next.js, Android, Flutter, React Native.

Fun fact: This plugin can release itself. We used /release:release to publish v1.2.0.

Sample Output

This plugin documents itself. View real output in this repo:

Configuration

Model Selection

On first run, you'll be prompted to choose which model to use:

This allows Opus users to hand off tasks to a faster model. Your choice can be saved to config.

Command Flags

/release:changelog --auto          # Run all follow-ups automatically
/release:changelog --skip          # No follow-ups
/release:changelog --decisions     # Auto-run decisions only
/release:changelog --no-whattotest # Skip whattotest prompt

Persistent Config

Create .claude/config.json in your project (a sample is included). Settings are namespaced under release-plugin:

{
  "release-plugin": {
    "model": "claude-sonnet-4-20250514",
    "changelog": {
      "outputPath": "./changelog.md",
      "followUp": {
        "decisions": "ask",
        "whattotest": "ask"
      }
    },
    "decisions": {
      "outputPath": "./decisions.md"
    },
    "whattotest": {
      "onExisting": "ask"
    },
    "release": {
      "gitMode": "auto"
    },
    "xcbuild": {
      "scheme": "MyApp",
      "simulatorId": "UUID",
      "showWarnings": true
    }
  }
}

When prompted for choices, you can save them to config for future runs.

Command-line flags override config settings.

License

MIT