Skip to content
Back to search

claude-code-ios-dev-guide

A comprehensive guide for setting up Claude Code CLI with PRD-driven workflows, extended thinking (ultrathink), and planning modes optimized for Swift/SwiftUI iOS development.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/keskinonur-claude-code-ios-dev-guide/badge.svg)](/listings/keskinonur-claude-code-ios-dev-guide)

HTML

<a href="/listings/keskinonur-claude-code-ios-dev-guide"><img src="/api/listings/keskinonur-claude-code-ios-dev-guide/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Native Installation (Recommended)

# macOS/Linux - Native installer (no Node.js required)
curl -fsSL https://claude.ai/install.sh | bash

# Or install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

NPM Installation (Alternative)

# Global npm install (do NOT use sudo)
npm install -g @anthropic-ai/claude-code

# Migrate existing npm install to native
claude install

Authentication

# Start Claude Code and authenticate via OAuth
claude

# Or set API key environment variable
export ANTHROPIC_API_KEY="your-key-here"

Model Selection

# Use specific model at startup
claude --model claude-opus-4-5-20250929
claude --model claude-sonnet-4-5-20250929
claude --model claude-3-5-haiku-20241022

# Or set default model
export ANTHROPIC_MODEL="claude-sonnet-4-5-20250929"

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 2,194 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Code CLI - Complete iOS Development Setup Guide
  2. > A comprehensive guide for setting up Claude Code CLI with PRD-driven workflows, extended thinking (ultrathink), and planning modes optimized for Swift/SwiftUI iOS development.
  3. ---
  4. ## Table of Contents
  5. 1. [Installation](#1-installation)
  6. 2. [Configuration Hierarchy](#2-configuration-hierarchy)
  7. 3. [CLAUDE.md Setup for iOS Projects](#3-claudemd-setup-for-ios-projects)
  8. 4. [PRD-Driven Development Workflow](#4-prd-driven-development-workflow)
  9. 5. [Extended Thinking & Ultrathink](#5-extended-thinking--ultrathink)
  10. 6. [Plan Mode Configuration](#6-plan-mode-configuration)
  11. 7. [XcodeBuildMCP Integration](#7-xcodebuildmcp-integration)
  12. 8. [Custom Slash Commands for iOS](#8-custom-slash-commands-for-ios)
  13. 9. [Agent Skills](#9-agent-skills)
  14. 10. [Subagents Configuration](#10-subagents-configuration)
  15. 11. [Output Styles](#11-output-styles)
  16. 12. [Plugins System](#12-plugins-system)
  17. 13. [Sandbox Mode & Safe Development](#13-sandbox-mode--safe-development)
  18. 14. [Settings & Permissions](#14-settings--permissions)
  19. 15. [Hooks for Swift Development](#15-hooks-for-swift-development)
  20. 16. [Complete Project Structure](#16-complete-project-structure)
  21. 17. [Best Practices & Tips](#17-best-practices--tips)
  22. ---
  23. ## 1. Installation
  24. ### Native Installation (Recommended)
  25. ```bash
  26. # macOS/Linux - Native installer (no Node.js required)
  27. curl -fsSL https://claude.ai/install.sh | bash
  28. # Or install latest version
  29. curl -fsSL https://claude.ai/install.sh | bash -s latest
  30. ```
  31. ### NPM Installation (Alternative)
  32. ```bash
  33. # Global npm install (do NOT use sudo)
  34. npm install -g @anthropic-ai/claude-code
  35. # Migrate existing npm install to native
  36. claude install
  37. ```
  38. ### Authentication
  39. ```bash
  40. # Start Claude Code and authenticate via OAuth
  41. claude
  42. # Or set API key environment variable
  43. export ANTHROPIC_API_KEY="your-key-here"
  44. ```
  45. ### Model Selection
  46. ```bash
  47. # Use specific model at startup
  48. claude --model claude-opus-4-5-20250929
  49. claude --model claude-sonnet-4-5-20250929
  50. claude --model claude-3-5-haiku-20241022
  51. # Or set default model
  52. export ANTHROPIC_MODEL="claude-sonnet-4-5-20250929"
  53. ```
  54. ---
  55. ## 2. Configuration Hierarchy
  56. Claude Code uses a layered configuration system where each level can override the one below:
  57. ```
  58. Priority (Highest to Lowest):
  59. ├── 1. Session flags (--model, --permission-mode)
  60. ├── 2. Environment variables
  61. ├── 3. .claude/settings.local.json (local - personal, gitignored)
  62. ├── 4. .claude/settings.json (project - shared with team)
  63. └── 5. ~/.claude/settings.json (user - global)
  64. ```
  65. ### Configuration Scopes
  66. | Scope | Description | Storage |
  67. |-------|-------------|---------|
  68. | **local** | Available only to you in current project (default for MCP) | `.claude/settings.local.json` |
  69. | **project** | Shared with team via git | `.claude/settings.json`, `.mcp.json` |
  70. | **user** | Available across all your projects | `~/.claude/settings.json` |
  71. ### Key Configuration Files
  72. | File | Scope | Git Status | Purpose |
  73. |------|-------|------------|---------|
  74. | `~/.claude/settings.json` | User | N/A | Global preferences |
  75. | `~/.claude/CLAUDE.md` | User | N/A | Global instructions |
  76. | `~/.claude/skills/` | User | N/A | Personal Agent Skills |
  77. | `~/.claude/commands/` | User | N/A | Personal slash commands |
  78. | `.claude/settings.json` | Project | Committed | Team settings |
  79. | `.claude/settings.local.json` | Local | Gitignored | Personal overrides |
  80. | `.mcp.json` | Project | Committed | Shared MCP servers |
  81. | `CLAUDE.md` | Project | Committed | Main project context |
  82. | `.claude/skills/` | Project | Committed | Project Agent Skills |
  83. | `.claude/commands/` | Project | Committed | Project slash commands |
  84. | `.claude/agents/` | Project | Committed | Project subagents |
  85. ---
  86. ## 3. CLAUDE.md Setup for iOS Projects
  87. The `CLAUDE.md` file is your primary context provider. Claude automatically loads it at session start.
  88. ### Root CLAUDE.md Template for iOS
  89. Create `CLAUDE.md` in your project root:
  90. ```markdown
  91. # Project: [Your App Name]
  92. ## Quick Reference
  93. - **Platform**: iOS 17+ / macOS 14+
  94. - **Language**: Swift 6.0
  95. - **UI Framework**: SwiftUI
  96. - **Architecture**: MVVM with @Observable
  97. - **Minimum Deployment**: iOS 17.0
  98. - **Package Manager**: Swift Package Manager
  99. ## XcodeBuildMCP Integration
  100. **IMPORTANT**: This project uses XcodeBuildMCP for all Xcode operations.
  101. - Build: `mcp__xcodebuildmcp__build_sim_name_proj`
  102. - Test: `mcp__xcodebuildmcp__test_sim_name_proj`
  103. - Clean: `mcp__xcodebuildmcp__clean`
  104. ## Project Structure
  105. ```
  106. MyApp/
  107. ├── App/ # App entry point, App delegate
  108. ├── Features/ # Feature modules
  109. │ ├── [FeatureName]/
  110. │ │ ├── Views/ # SwiftUI views
  111. │ │ ├── ViewModels/ # @Observable classes
  112. │ │ └── Models/ # Data models
  113. ├── Core/ # Shared utilities
  114. │ ├── Extensions/
  115. │ ├── Services/
  116. │ └── Networking/
  117. ├── Resources/ # Assets, Localizations
  118. └── Tests/
  119. ```
  120. ## Coding Standards
  121. ### Swift Style
  122. - Use Swift 6 strict concurrency
  123. - Prefer `@Observable` over `ObservableObject`
  124. - Use `async/await` for all async operations
  125. - Follow Apple's Swift API Design Guidelines
  126. - Use `guard` for early exits
  127. - Prefer value types (structs) over reference types (classes)
  128. ### SwiftUI Patterns
  129. - Extract views when they exceed 100 lines
  130. - Use `@State` for local view state only
  131. - Use `@Environment` for dependency injection
  132. - Prefer `NavigationStack` over deprecated `NavigationView`
  133. - Use `@Bindable` for bindings to @Observable objects
  134. ### Navigation Pattern
  135. ```swift
  136. // Use NavigationStack with type-safe routing
  137. enum Route: Hashable {
  138. case detail(Item)
  139. case settings
  140. }
  141. NavigationStack(path: $router.path) {
  142. ContentView()
  143. .navigationDestination(for: Route.self) { route in
  144. // Handle routing
  145. }
  146. }
  147. ```
  148. ### Error Handling
  149. ```swift
  150. // Always use typed errors
  151. enum AppError: LocalizedError {
  152. case networkError(underlying: Error)
  153. case validationError(message: String)
  154. var errorDescription: String? {
  155. switch self {
  156. case .networkError(let error): return error.localizedDescription
  157. case .validationError(let msg): return msg
  158. }
  159. }
  160. }
  161. ```
  162. ## Testing Requirements
  163. - Unit tests for all ViewModels
  164. - UI tests for critical user flows
  165. - Use Swift Testing framework (`@Test`, `#expect`)
  166. - Minimum 80% code coverage for business logic
  167. ## DO NOT
  168. - Write UITests during scaffolding phase
  169. - Use deprecated APIs (UIKit when SwiftUI suffices)
  170. - Create massive monolithic views
  171. - Use force unwrapping (`!`) without justification
  172. - Ignore Swift 6 concurrency warnings
  173. ## Planning Workflow
  174. When starting new features:
  175. 1. Read the PRD from `docs/PRD.md`
  176. 2. Create feature spec in `docs/specs/[feature-name].md`
  177. 3. Use `ultrathink` for architectural decisions
  178. 4. Use Plan Mode (`Shift+Tab`) for implementation strategy
  179. 5. Implement incrementally with tests
  180. ## Memory Imports
  181. @import docs/PRD.md
  182. @import docs/ARCHITECTURE.md
  183. @import docs/ROADMAP.md
  184. ```
  185. ### Nested CLAUDE.md for Feature Directories
  186. Create `.claude/CLAUDE.md` or `Features/[FeatureName]/CLAUDE.md`:
  187. ```markdown
  188. # [Feature Name] Module
  189. ## Purpose
  190. [Description of what this feature does]
  191. ## Architecture
  192. - Uses MVVM with @Observable ViewModels
  193. - Parent stores create child stores for modal presentations
  194. ## Navigation Pattern
  195. ### Sheet-Based Navigation
  196. **Pattern**: Parent stores create optional child stores for modal presentations
  197. **Rules**:
  198. 1. Parent ViewModel holds `@Published var childViewModel: ChildViewModel?`
  199. 2. View observes and presents sheet when non-nil
  200. 3. Dismissal sets childViewModel to nil
  201. ### Example
  202. ```swift
  203. @Observable
  204. final class ParentViewModel {
  205. var detailViewModel: DetailViewModel?
  206. func showDetail(for item: Item) {
  207. detailViewModel = DetailViewModel(item: item)
  208. }
  209. }
  210. ```
  211. ## Testing
  212. Run tests: `mcp__xcodebuildmcp__swift_package_test`
  213. ```
  214. ---
  215. ## 4. PRD-Driven Development Workflow
  216. ### Directory Structure for PRD Workflow
  217. ```
  218. docs/
  219. ├── PRD.md # Main Product Requirements Document
  220. ├── ARCHITECTURE.md # System architecture decisions
  221. ├── ROADMAP.md # Development roadmap & priorities
  222. ├── specs/ # Feature specifications
  223. │ ├── 000-project-setup.md
  224. │ ├── 001-authentication.md
  225. │ ├── 002-dashboard.md
  226. │ └── template.md
  227. └── tasks/ # Task breakdowns
  228. ├── 000-sample.md
  229. └── [feature]-tasks.md
  230. ```
  231. ### PRD Template (`docs/PRD.md`)
  232. ```markdown
  233. # Product Requirements Document: [App Name]
  234. ## Executive Summary
  235. [Brief description of the product and its primary value proposition]
  236. ## Problem Statement
  237. [What problem does this solve? Who experiences this problem?]
  238. ## Target Users
  239. - **Primary**: [Description]
  240. - **Secondary**: [Description]
  241. ## Success Metrics
  242. | Metric | Target | Measurement |
  243. |--------|--------|-------------|
  244. | User Retention | 40% D7 | Analytics |
  245. | App Rating | 4.5+ | App Store |
  246. | Crash-Free Rate | 99.5% | Crashlytics |
  247. ## Core Features
  248. ### Feature 1: [Name]
  249. **Priority**: P0 (Must Have)
  250. **Description**: [Detailed description]
  251. **User Stories**:
  252. - As a [user type], I want [action] so that [benefit]
  253. **Acceptance Criteria**:
  254. - [ ] Criterion 1
  255. - [ ] Criterion 2
  256. **Technical Requirements**:
  257. - iOS 17+ required
  258. - Offline support needed
  259. - Data persistence via SwiftData
  260. ### Feature 2: [Name]
  261. [Continue pattern...]
  262. ## Non-Functional Requirements
  263. - **Performance**: App launch < 2s, smooth 60fps scrolling
  264. - **Accessibility**: WCAG 2.1 AA compliance
  265. - **Localization**: English (primary), [other languages]
  266. - **Security**: Keychain for credentials, certificate pinning
  267. ## Out of Scope (v1.0)
  268. - [Feature explicitly not included]
  269. ## Technical Constraints
  270. - Swift 6.0+ with strict concurrency
  271. - SwiftUI-only (no UIKit unless necessary)
  272. - SwiftData for persistence
  273. - Minimum iOS 17.0
  274. ## Timeline
  275. | Phase | Duration | Deliverables |
  276. |-------|----------|--------------|
  277. | Design | 2 weeks | Figma mockups |
  278. | Development | 8 weeks | MVP features |
  279. | Testing | 2 weeks | QA sign-off |
  280. | Launch | 1 week | App Store submission |
  281. ```
  282. ### Feature Spec Template (`docs/specs/template.md`)
  283. ```markdown
  284. # Feature Specification: [Feature Name]
  285. **Status**: Draft | In Review | Approved | In Progress | Complete
  286. **Priority**: P0 | P1 | P2
  287. **PRD Reference**: Section [X]
  288. **Author**: [Name]
  289. **Last Updated**: [Date]
  290. ## Overview
  291. [Brief description of the feature]
  292. ## User Stories
  293. 1. As a [user], I want [action] so that [benefit]
  294. 2. ...
  295. ## Acceptance Criteria
  296. - [ ] AC1: [Specific, testable criterion]
  297. - [ ] AC2: ...
  298. ## Technical Design
  299. ### Architecture
  300. [How this feature fits into the overall architecture]
  301. ### Data Models
  302. ```swift
  303. struct FeatureModel: Codable, Identifiable {
  304. let id: UUID
  305. // ...
  306. }
  307. ```
  308. ### API Endpoints (if applicable)
  309. ```
  310. GET /api/v1/feature
  311. POST /api/v1/feature
  312. ```
  313. ### Dependencies
  314. - [ ] Core networking module
  315. - [ ] SwiftData setup
  316. ## UI/UX Design
  317. - Figma Link: [URL]
  318. - Key screens: [List]
  319. ## Edge Cases
  320. 1. [Edge case and how to handle]
  321. ## Testing Plan
  322. - Unit tests for ViewModel logic
  323. - UI tests for critical flows
  324. - Performance tests for data loading
  325. ## Rollout Plan
  326. - [ ] Feature flag: `feature_[name]_enabled`
  327. - [ ] A/B test configuration
  328. ## Open Questions
  329. - [ ] Question 1?
  330. ```
  331. ### Task File Template (`docs/tasks/feature-tasks.md`)
  332. ```markdown
  333. # Tasks: [Feature Name]
  334. **Feature Spec**: `docs/specs/[feature].md`
  335. **Status**: Not Started | In Progress | Complete
  336. ## Progress Summary
  337. - Total Steps: X
  338. - Completed: Y
  339. - Current: Step Z
  340. ## Steps
  341. ### Step 1: [Task Name]
  342. - [ ] Subtask 1
  343. - [ ] Subtask 2
  344. **Notes**: [Implementation notes]
  345. ### Step 2: [Task Name]
  346. - [ ] Subtask 1
  347. **Notes**:
  348. ## Changes Log
  349. | Date | Step | Changes |
  350. |------|------|---------|
  351. | YYYY-MM-DD | 1 | Initial implementation |
  352. ```
  353. ### PRD-Driven Slash Commands
  354. Create `.claude/commands/` with these files:
  355. **`.claude/commands/create-prd.md`**
  356. ```markdown
  357. ---
  358. description: Create a new PRD from requirements discussion
  359. allowed-tools: Read, Write, Edit
  360. ---
  361. # Create Product Requirements Document
  362. Based on our discussion, create a comprehensive PRD in `docs/PRD.md`.
  363. Follow this structure:
  364. 1. Executive Summary
  365. 2. Problem Statement
  366. 3. Target Users
  367. 4. Success Metrics
  368. 5. Core Features with user stories and acceptance criteria
  369. 6. Non-Functional Requirements
  370. 7. Technical Constraints
  371. 8. Timeline
  372. Ask clarifying questions before writing. Use ultrathink for comprehensive planning.
  373. ```
  374. **`.claude/commands/generate-spec.md`**
  375. ```markdown
  376. ---
  377. description: Generate feature specification from PRD
  378. argument-hint: <feature-name>
  379. allowed-tools: Read, Write
  380. ---
  381. # Generate Feature Specification
  382. Read the PRD at `docs/PRD.md` and create a detailed specification for: $ARGUMENTS
  383. 1. Extract relevant user stories and requirements
  384. 2. Define acceptance criteria
  385. 3. Design technical architecture
  386. 4. Create the spec file at `docs/specs/$ARGUMENTS.md`
  387. ultrathink about the technical design before writing.
  388. ```
  389. **`.claude/commands/generate-tasks.md`**
  390. ```markdown
  391. ---
  392. description: Break down feature spec into implementable tasks
  393. argument-hint: <feature-name>
  394. allowed-tools: Read, Write
  395. ---
  396. # Generate Task Breakdown
  397. Read the specification at `docs/specs/$ARGUMENTS.md` and create a detailed task breakdown.
  398. 1. Identify all implementation steps
  399. 2. Order by dependencies
  400. 3. Estimate complexity
  401. 4. Create `docs/tasks/$ARGUMENTS-tasks.md`
  402. Each task should be completable in a single session.
  403. ```
  404. ---
  405. ## 5. Extended Thinking & Ultrathink
  406. Extended thinking is **disabled by default** in Claude Code. You can enable it on-demand.
  407. ### Enabling Extended Thinking
  408. | Method | Description |
  409. |--------|-------------|
  410. | **Tab key** | Press `Tab` to toggle Thinking on/off during session |
  411. | **Prompt triggers** | Use phrases like "think", "think hard", "ultrathink" |
  412. | **Environment variable** | Set `MAX_THINKING_TOKENS` for permanent enablement |
  413. ### Thinking Budget Hierarchy
  414. Claude Code maps keywords to thinking token budgets:
  415. | Keyword | Budget | Best For |
  416. |---------|--------|----------|
  417. | `think` | ~4K tokens | Simple planning, quick decisions |
  418. | `think hard` / `megathink` / `think more` / `think a lot` | ~10K tokens | Medium complexity |
  419. | `think harder` / `think longer` | ~16K tokens | Complex analysis |
  420. | `ultrathink` | ~32K tokens (max) | Architecture, critical debugging |
  421. ### Usage Examples
  422. ```
  423. # Simple planning
  424. "Think about how to structure this view"
  425. # Medium complexity
  426. "Think hard about the navigation architecture for this feature"
  427. # Complex architectural decisions
  428. "Ultrathink about how to design the offline sync system for this app"
  429. ```
  430. ### Viewing Thinking Process
  431. - Press `Ctrl+O` to toggle verbose mode and see Claude's thinking process
  432. - Thinking appears as *italic gray text* above the response
  433. ### When to Use Ultrathink
  434. ✅ **Use Ultrathink for:**
  435. - System architecture decisions
  436. - Complex debugging (e.g., race conditions, memory leaks)
  437. - Large-scale refactoring planning
  438. - Migration strategies (UIKit → SwiftUI, CoreData → SwiftData)
  439. - Performance optimization analysis
  440. - Unfamiliar codebase exploration
  441. ❌ **Avoid Ultrathink for:**
  442. - Simple code changes
  443. - Well-specified tasks with clear steps
  444. - Rapid prototyping iterations
  445. - Tasks where speed matters more than perfection
  446. ### Combining with Plan Mode
  447. ```bash
  448. # Start session in Plan Mode with ultrathink
  449. claude --permission-mode plan
  450. # Then in session:
  451. "Ultrathink about how to implement the authentication flow.
  452. Read the PRD first, then create a comprehensive plan."
  453. ```
  454. ### Cost Awareness
  455. | Mode | Approx. Cost per Task |
  456. |------|----------------------|
  457. | Standard | ~$0.02-0.05 |
  458. | think | ~$0.06 |
  459. | think hard | ~$0.15 |
  460. | ultrathink | ~$0.30-0.50 |
  461. Use `/cost` command to monitor token usage during sessions.
  462. ---
  463. ## 6. Plan Mode Configuration
  464. ### What is Plan Mode?
  465. Plan Mode instructs Claude to analyze codebases with **read-only operations** - perfect for:
  466. - Multi-step implementation planning
  467. - Code exploration before making changes
  468. - Interactive development with iterative direction refinement
  469. ### Enabling Plan Mode
  470. ```bash
  471. # Start new session in Plan Mode
  472. claude --permission-mode plan
  473. # Or use -p flag for headless Plan Mode query
  474. claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
  475. ```
  476. ### Configure as Default
  477. ```json
  478. // .claude/settings.json
  479. {
  480. "permissions": {
  481. "defaultMode": "plan"
  482. }
  483. }
  484. ```
  485. ### During Session
  486. - Press `Shift+Tab` to cycle: Normal → Auto-Accept → Plan Mode
  487. - Plan Mode indicator: `⏸ plan mode on`
  488. - Auto-Accept indicator: `⏵⏵ accept edits on`
  489. - Plan Mode restricts Claude to read-only operations
  490. ### Opus Plan Mode Strategy
  491. Use Opus for planning, Sonnet for execution:
  492. ```bash
  493. # Plan with Opus
  494. claude --model claude-opus-4-5-20250929 --permission-mode plan
  495. # Execute with Sonnet (more cost-effective)
  496. claude --model claude-sonnet-4-5-20250929
  497. ```
  498. ### Plan Mode Slash Command
  499. **`.claude/commands/plan-feature.md`**
  500. ```markdown
  501. ---
  502. description: Create implementation plan for a feature
  503. argument-hint: <feature-name>
  504. allowed-tools: Read, Grep, Glob
  505. model: claude-opus-4-5-20250929
  506. ---
  507. # Plan Feature Implementation
  508. ultrathink and create a comprehensive implementation plan for: $ARGUMENTS
  509. ## Steps
  510. 1. Read the PRD and feature spec
  511. 2. Analyze the existing codebase structure
  512. 3. Identify dependencies and integration points
  513. 4. Create step-by-step implementation plan
  514. 5. Identify potential challenges and solutions
  515. 6. Estimate effort for each step
  516. Output the plan to `docs/tasks/$ARGUMENTS-plan.md`
  517. DO NOT write any code. This is planning only.
  518. ```
  519. ---
  520. ## 7. XcodeBuildMCP Integration
  521. XcodeBuildMCP is the essential MCP server for iOS development with Claude Code.
  522. ### MCP Transport Types
  523. | Type | Description | Use Case |
  524. |------|-------------|----------|
  525. | **HTTP** | Recommended for remote servers | Cloud services (Notion, GitHub) |
  526. | **SSE** | Server-Sent Events (deprecated) | Legacy remote servers |
  527. | **stdio** | Local process | XcodeBuildMCP, local tools |
  528. ### Installation
  529. ```bash
  530. # Add XcodeBuildMCP (stdio transport)
  531. claude mcp add --transport stdio XcodeBuildMCP -- npx -y xcodebuildmcp@latest
  532. # With environment variables
  533. claude mcp add --transport stdio XcodeBuildMCP \
  534. --env INCREMENTAL_BUILDS_ENABLED=true \
  535. --env XCODEBUILDMCP_DYNAMIC_TOOLS=true \
  536. -- npx -y xcodebuildmcp@latest
  537. # Specify scope
  538. claude mcp add --transport stdio XcodeBuildMCP --scope project -- npx -y xcodebuildmcp@latest
  539. ```
  540. > **Note**: The `--` separates Claude's flags from the server command. Everything after `--` is the command to run the MCP server.
  541. ### MCP Scopes
  542. | Scope | Description | Storage |
  543. |-------|-------------|---------|
  544. | **local** (default) | Only you, current project | `~/.claude.json` under project path |
  545. | **project** | Team-shared via git | `.mcp.json` |
  546. | **user** | You, all projects | `~/.claude.json` |
  547. ### Manual Configuration (`.mcp.json`)
  548. Create `.mcp.json` in project root for team-shared MCP servers:
  549. ```json
  550. {
  551. "mcpServers": {
  552. "XcodeBuildMCP": {
  553. "command": "npx",
  554. "args": ["-y", "xcodebuildmcp@latest"],
  555. "env": {
  556. "INCREMENTAL_BUILDS_ENABLED": "true",
  557. "XCODEBUILDMCP_SENTRY_DISABLED": "true",
  558. "XCODEBUILDMCP_DYNAMIC_TOOLS": "true",
  559. "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery,swift-package"
  560. }
  561. }
  562. }
  563. }
  564. ```
  565. ### Environment Variable Expansion
  566. `.mcp.json` supports environment variable expansion:
  567. ```json
  568. {
  569. "mcpServers": {
  570. "custom-server": {
  571. "command": "${HOME}/tools/server",
  572. "env": {
  573. "API_KEY": "${MY_API_KEY}",
  574. "BASE_URL": "${API_URL:-https://default.example.com}"
  575. }
  576. }
  577. }
  578. }
  579. ```
  580. Syntax:
  581. - `${VAR}` - Expands to variable value
  582. - `${VAR:-default}` - Uses default if VAR not set
  583. ### Managing MCP Servers
  584. ```bash
  585. # List all configured servers
  586. claude mcp list
  587. # Get details for a specific server
  588. claude mcp get XcodeBuildMCP
  589. # Remove a server
  590. claude mcp remove XcodeBuildMCP
  591. # Check server status (in session)
  592. /mcp
  593. # Authenticate with OAuth-enabled servers
  594. /mcp # Then select "Authenticate"
  595. ```
  596. ### MCP Output Limits
  597. ```bash
  598. # Set higher limit for large outputs (default: 25,000 tokens)
  599. export MAX_MCP_OUTPUT_TOKENS=50000
  600. claude
  601. # Set MCP server startup timeout (default: 60 seconds)
  602. MCP_TIMEOUT=10000 claude
  603. ```
  604. ### MCP Resources with @ Mentions
  605. Reference MCP resources using `@server:protocol://resource/path`:
  606. ```
  607. > Analyze @github:issue://123 and suggest a fix
  608. > Review the documentation at @docs:file://api/authentication
  609. ```
  610. ### Available XcodeBuildMCP Tools
  611. | Tool | Description |
  612. |------|-------------|
  613. | `mcp__xcodebuildmcp__discover_projects` | Find Xcode projects/workspaces |
  614. | `mcp__xcodebuildmcp__list_schemes` | List available build schemes |
  615. | `mcp__xcodebuildmcp__build_sim_name_proj` | Build for iOS simulator |
  616. | `mcp__xcodebuildmcp__build_device_proj` | Build for physical device |
  617. | `mcp__xcodebuildmcp__test_sim_name_proj` | Run tests on simulator |
  618. | `mcp__xcodebuildmcp__clean` | Clean build products |
  619. | `mcp__xcodebuildmcp__list_simulators` | List available simulators |
  620. | `mcp__xcodebuildmcp__boot_simulator` | Boot a simulator |
  621. | `mcp__xcodebuildmcp__install_app` | Install app on simulator/device |
  622. | `mcp__xcodebuildmcp__launch_app` | Launch installed app |
  623. | `mcp__xcodebuildmcp__capture_logs` | Capture runtime logs |
  624. | `mcp__xcodebuildmcp__screenshot` | Capture simulator screenshot |
  625. | `mcp__xcodebuildmcp__swift_package_build` | Build Swift package |
  626. | `mcp__xcodebuildmcp__swift_package_test` | Run Swift package tests |
  627. | `mcp__xcodebuildmcp__create_project` | Scaffold new iOS/macOS project |
  628. ### Usage in CLAUDE.md
  629. ```markdown
  630. ## Build Commands
  631. - **Build**: Use `mcp__xcodebuildmcp__build_sim_name_proj` for simulator builds
  632. - **Test**: Use `mcp__xcodebuildmcp__test_sim_name_proj` for running tests
  633. - **Clean**: Use `mcp__xcodebuildmcp__clean` before major rebuilds
  634. - **Logs**: Use `mcp__xcodebuildmcp__capture_logs` to debug runtime issues
  635. ```
  636. ---
  637. ## 8. Custom Slash Commands for iOS
  638. ### Project Commands (`.claude/commands/`)
  639. **build.md**
  640. ```markdown
  641. ---
  642. description: Build the iOS project intelligently
  643. allowed-tools: mcp__xcodebuildmcp__*
  644. ---
  645. # Build Project
  646. Detect the project type and build appropriately:
  647. 1. Check for .xcworkspace or .xcodeproj
  648. 2. Use XcodeBuildMCP to build for iOS Simulator
  649. 3. Report any build errors with suggested fixes
  650. ```
  651. **test.md**
  652. ```markdown
  653. ---
  654. description: Run all relevant tests
  655. allowed-tools: mcp__xcodebuildmcp__*, Bash(swift *)
  656. ---
  657. # Run Tests
  658. Based on current context:
  659. - For main app: `mcp__xcodebuildmcp__test_sim_name_proj`
  660. - For Swift packages: `mcp__xcodebuildmcp__swift_package_test`
  661. - Report test results and any failures
  662. ```
  663. **run-app.md**
  664. ```markdown
  665. ---
  666. description: Build and launch app on simulator
  667. allowed-tools: mcp__xcodebuildmcp__*
  668. ---
  669. # Build and Run
  670. 1. List available simulators
  671. 2. Build the app for the default simulator (iPhone 15)
  672. 3. Boot the simulator if needed
  673. 4. Install and launch the app
  674. 5. Start capturing logs
  675. ```
  676. **create-view.md**
  677. ```markdown
  678. ---
  679. description: Create a new SwiftUI view with ViewModel
  680. argument-hint: <ViewName>
  681. allowed-tools: Read, Write
  682. ---
  683. # Create SwiftUI View: $ARGUMENTS
  684. Create a new SwiftUI view following project patterns:
  685. 1. Read existing views for style reference
  686. 2. Create `$ARGUMENTS.swift` in appropriate Features directory
  687. 3. Create `${ARGUMENTS}ViewModel.swift` as @Observable class
  688. 4. Add preview provider
  689. 5. Follow project's navigation and styling patterns
  690. ```
  691. **refactor-view.md**
  692. ```markdown
  693. ---
  694. description: Extract and refactor a SwiftUI view
  695. argument-hint: <source-file>
  696. allowed-tools: Read, Write, Edit
  697. ---
  698. # Refactor View: $ARGUMENTS
  699. Analyze the view and:
  700. 1. Identify extractable subviews (>50 lines or reusable)
  701. 2. Extract to separate files
  702. 3. Create appropriate ViewModels if needed
  703. 4. Ensure proper data flow with bindings
  704. 5. Add documentation comments
  705. ```
  706. **fix-build.md**
  707. ```markdown
  708. ---
  709. description: Diagnose and fix build errors
  710. allowed-tools: mcp__xcodebuildmcp__*, Read, Write, Edit, Bash(swift *)
  711. ---
  712. # Fix Build Errors
  713. ultrathink about the build errors:
  714. 1. Run a clean build to get fresh errors
  715. 2. Analyze each error
  716. 3. Propose fixes
  717. 4. Implement fixes one at a time
  718. 5. Verify build succeeds
  719. ```
  720. **implement-feature.md**
  721. ```markdown
  722. ---
  723. description: Implement a feature from spec
  724. argument-hint: <feature-name>
  725. allowed-tools: Read, Write, Edit, mcp__xcodebuildmcp__*
  726. ---
  727. # Implement Feature: $ARGUMENTS
  728. Follow the PRD workflow:
  729. 1. Read `docs/specs/$ARGUMENTS.md` for requirements
  730. 2. Read `docs/tasks/$ARGUMENTS-tasks.md` for task breakdown
  731. 3. Implement the current uncompleted task
  732. 4. Write tests for the implementation
  733. 5. Update task progress in the tasks file
  734. 6. Build and test
  735. Stop after completing each task and wait for approval.
  736. ```
  737. ### Personal Commands (`~/.claude/commands/`)
  738. **swift-style.md**
  739. ```markdown
  740. ---
  741. description: Check Swift style and conventions
  742. allowed-tools: Bash(swiftlint *), Bash(swift-format *)
  743. ---
  744. # Swift Style Check
  745. Run linting and formatting checks:
  746. 1. Run SwiftLint if configured
  747. 2. Run swift-format check
  748. 3. Report violations with suggested fixes
  749. ```
  750. ---
  751. ## 9. Agent Skills
  752. Agent Skills are **model-invoked** capabilities - Claude autonomously decides when to use them based on your request and the Skill's description. Unlike slash commands (user-invoked), Skills activate automatically when relevant.
  753. ### Creating Agent Skills
  754. Skills are stored as directories containing a `SKILL.md` file:
  755. | Location | Scope | Use Case |
  756. |----------|-------|----------|
  757. | `~/.claude/skills/skill-name/` | Personal | Your individual workflows |
  758. | `.claude/skills/skill-name/` | Project | Team-shared capabilities |
  759. ### Skill Structure
  760. **`.claude/skills/ios-testing/SKILL.md`**
  761. ```markdown
  762. ---
  763. name: ios-testing
  764. description: iOS testing expert for unit tests, UI tests, and test-driven development. Use when working with XCTest, testing SwiftUI views, or implementing test strategies.
  765. allowed-tools: Read, Grep, Glob, mcp__xcodebuildmcp__test_*
  766. ---
  767. # iOS Testing Expert
  768. ## Instructions
  769. 1. Analyze existing test coverage
  770. 2. Identify untested code paths
  771. 3. Generate comprehensive test cases
  772. 4. Use XCTest and Swift Testing frameworks
  773. ## Best Practices
  774. - Test behavior, not implementation
  775. - Use dependency injection for testability
  776. - Mock external dependencies
  777. - Target 80%+ code coverage for critical paths
  778. ```
  779. ### Skill with Restricted Tools
  780. Use `allowed-tools` to limit Claude's capabilities when the Skill is active:
  781. **`.claude/skills/code-analyzer/SKILL.md`**
  782. ```markdown
  783. ---
  784. name: code-analyzer
  785. description: Read-only code analysis for architecture review and code quality assessment. Use when reviewing PRs or analyzing codebase structure.
  786. allowed-tools: Read, Grep, Glob
  787. ---
  788. # Code Analyzer (Read-Only)
  789. ## Review Checklist
  790. 1. Code organization and structure
  791. 2. Error handling patterns
  792. 3. Performance considerations
  793. 4. Security concerns
  794. 5. Test coverage gaps
  795. Provide detailed feedback without modifying files.
  796. ```
  797. ### Multi-File Skill
  798. Skills can include supporting files:
  799. ```
  800. .claude/skills/swiftui-components/
  801. ├── SKILL.md
  802. ├── PATTERNS.md
  803. ├── REFERENCE.md
  804. └── templates/
  805. ├── view-template.swift
  806. └── viewmodel-template.swift
  807. ```
  808. **SKILL.md**
  809. ```markdown
  810. ---
  811. name: swiftui-components
  812. description: SwiftUI component expert for building reusable views, custom modifiers, and view compositions. Use when creating new SwiftUI views or refactoring UI code.
  813. ---
  814. # SwiftUI Components
  815. ## Quick Start
  816. For standard patterns, see [PATTERNS.md](PATTERNS.md).
  817. For API reference, see [REFERENCE.md](REFERENCE.md).
  818. ## Instructions
  819. 1. Analyze the required component functionality
  820. 2. Check existing components for reuse
  821. 3. Apply templates from templates/ directory
  822. 4. Follow project styling conventions
  823. ```
  824. ### Managing Skills
  825. ```bash
  826. # View available Skills
  827. > "What Skills are available?"
  828. # Skills activate automatically based on context
  829. > "Help me write tests for the authentication module"
  830. # → iOS testing Skill activates automatically
  831. # Explicitly check Skill files
  832. ls ~/.claude/skills/
  833. ls .claude/skills/
  834. ```
  835. ### Skill Best Practices
  836. | Practice | Example |
  837. |----------|---------|
  838. | **Focused scope** | "PDF form filling" not "Document processing" |
  839. | **Clear triggers** | Include when to use in description |
  840. | **Specific keywords** | "Use when working with XCTest, testing SwiftUI views" |
  841. ---
  842. ## 10. Subagents Configuration
  843. Subagents are specialized AI assistants invoked to handle specific task types.
  844. ### Creating iOS-Specific Subagents
  845. Subagents are defined in `.claude/agents/` or `~/.claude/agents/`
  846. **`.claude/agents/ios-architect.md`**
  847. ```markdown
  848. ---
  849. name: ios-architect
  850. description: iOS architecture expert for system design and patterns
  851. model: claude-opus-4-5-20250929
  852. tools: Read, Grep, Glob
  853. ---
  854. You are an expert iOS architect specializing in Swift and SwiftUI.
  855. Your expertise includes:
  856. - MVVM, MVC, VIPER, Clean Architecture
  857. - Swift Concurrency (actors, async/await, Sendable)
  858. - SwiftUI navigation patterns
  859. - Dependency injection
  860. - SwiftData and Core Data
  861. - Modular app architecture
  862. When consulted:
  863. 1. Analyze the existing codebase structure
  864. 2. Consider scalability and maintainability
  865. 3. Propose patterns that fit the team's expertise
  866. 4. Provide concrete Swift code examples
  867. 5. Consider testing implications
  868. Focus on practical, production-ready advice.
  869. ```
  870. **`.claude/agents/swift-reviewer.md`**
  871. ```markdown
  872. ---
  873. name: swift-reviewer
  874. description: Code reviewer for Swift/SwiftUI code quality
  875. model: claude-sonnet-4-5-20250929
  876. tools: Read, Grep
  877. ---
  878. You are an expert Swift code reviewer.
  879. Review code for:
  880. - Swift 6 concurrency safety
  881. - Memory management (retain cycles, weak references)
  882. - SwiftUI best practices
  883. - API design guidelines compliance
  884. - Performance considerations
  885. - Test coverage
  886. - Documentation quality
  887. Provide specific, actionable feedback with code examples.
  888. ```
  889. **`.claude/agents/swiftui-specialist.md`**
  890. ```markdown
  891. ---
  892. name: swiftui-specialist
  893. description: SwiftUI expert for complex UI implementation
  894. tools: Read, Write, Edit
  895. ---
  896. You are a SwiftUI specialist with deep knowledge of:
  897. - Custom layouts and GeometryReader
  898. - Animations and transitions
  899. - Custom view modifiers
  900. - Preference keys
  901. - Environment and EnvironmentObject
  902. - NavigationStack and navigation patterns
  903. - Performance optimization
  904. - Accessibility
  905. When building UI:
  906. 1. Start with the simplest approach
  907. 2. Extract reusable components
  908. 3. Use proper state management
  909. 4. Ensure accessibility
  910. 5. Consider all device sizes
  911. ```
  912. ### Using Subagents
  913. ```
  914. # Explicit invocation
  915. "Use the ios-architect to design the data layer"
  916. # Automatic invocation (based on description matching)
  917. "Review this authentication code for security issues"
  918. # Claude may automatically invoke swift-reviewer
  919. ```
  920. ### Subagent for Research
  921. **`.claude/agents/ios-researcher.md`**
  922. ```markdown
  923. ---
  924. name: ios-researcher
  925. description: Research iOS APIs and best practices
  926. tools: WebSearch, WebFetch, Read
  927. ---
  928. You are an iOS research specialist.
  929. When researching:
  930. 1. Search Apple Developer documentation
  931. 2. Find relevant WWDC sessions
  932. 3. Check Swift Evolution proposals if relevant
  933. 4. Look for community best practices
  934. 5. Summarize findings with code examples
  935. Always cite sources and note iOS version requirements.
  936. ```
  937. ---
  938. ## 11. Output Styles
  939. Output Styles adapt Claude Code for different use cases by modifying its system prompt.
  940. ### Built-in Output Styles
  941. | Style | Description |
  942. |-------|-------------|
  943. | **Default** | Standard software engineering focus |
  944. | **Explanatory** | Provides educational "Insights" while coding |
  945. | **Learning** | Collaborative learn-by-doing with `TODO(human)` markers |
  946. ### Changing Output Style
  947. ```bash
  948. # Open style menu
  949. /output-style
  950. # Or switch directly
  951. /output-style explanatory
  952. /output-style learning
  953. ```
  954. ### Creating Custom Output Styles
  955. Create `.claude/output-styles/` or `~/.claude/output-styles/` files:
  956. **`.claude/output-styles/ios-mentor.md`**
  957. ```markdown
  958. ---
  959. name: iOS Mentor
  960. description: Teaching-focused style for iOS development with explanations and learning opportunities
  961. keep-coding-instructions: true
  962. ---
  963. # iOS Mentor Style
  964. You are an iOS development mentor helping developers learn Swift and SwiftUI.
  965. ## Behaviors
  966. 1. Explain **why** before showing **how**
  967. 2. Reference Apple documentation and WWDC sessions
  968. 3. Point out common pitfalls and Swift idioms
  969. 4. Suggest further learning resources
  970. 5. Add `// 💡 Learn: ...` comments explaining key concepts
  971. ## Teaching Approach
  972. - Start with the concept, then show implementation
  973. - Compare approaches when multiple valid options exist
  974. - Highlight Swift 6 and iOS 18 modern patterns
  975. ```
  976. ### Output Style vs Other Features
  977. | Feature | Purpose | Invocation |
  978. |---------|---------|------------|
  979. | **Output Style** | Changes system prompt behavior | Auto (session-wide) |
  980. | **Slash Commands** | Stored prompts | User types `/command` |
  981. | **Agent Skills** | Specialized capabilities | Auto (model decides) |
  982. | **Subagents** | Task delegation | Auto or explicit |
  983. ---
  984. ## 12. Plugins System
  985. Plugins extend Claude Code with custom functionality - commands, agents, Skills, hooks, and MCP servers bundled together.
  986. ### Installing Plugins
  987. ```bash
  988. # Open plugin manager
  989. /plugin
  990. # Install from official marketplace (auto-available)
  991. # Go to Discover tab, select plugin, choose scope
  992. # Add custom marketplace
  993. claude plugin marketplace add owner/repo
  994. # Install directly
  995. claude plugin install plugin-name@marketplace-name
  996. ```
  997. ### Plugin Scopes
  998. | Scope | Description |
  999. |-------|-------------|
  1000. | **user** | Available across all your projects |
  1001. | **local** | Only you, current project |
  1002. | **project** | Shared via git with team |
  1003. ### Official Marketplace
  1004. The official Anthropic marketplace includes:
  1005. - **Code Intelligence** plugins (LSP for Swift, Python, etc.)
  1006. - **Workflow** plugins for common tasks
  1007. - **Integration** plugins for external services
  1008. ### Creating a Plugin
  1009. ```
  1010. my-plugin/
  1011. ├── .claude-plugin/
  1012. │ └── plugin.json
  1013. ├── commands/
  1014. │ └── my-command.md
  1015. ├── agents/
  1016. │ └── my-agent.md
  1017. ├── skills/
  1018. │ └── my-skill/
  1019. │ └── SKILL.md
  1020. ├── hooks/
  1021. │ └── hooks.json
  1022. └── .mcp.json
  1023. ```
  1024. **`.claude-plugin/plugin.json`**
  1025. ```json
  1026. {
  1027. "name": "ios-toolkit",
  1028. "version": "1.0.0",
  1029. "description": "iOS development toolkit with commands, agents, and MCP integration",
  1030. "author": "Your Name"
  1031. }
  1032. ```
  1033. ### Plugin-Provided MCP Servers
  1034. Plugins can bundle MCP servers in `.mcp.json`:
  1035. ```json
  1036. {
  1037. "mcpServers": {
  1038. "plugin-server": {
  1039. "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
  1040. "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
  1041. "env": {
  1042. "DATA_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
  1043. }
  1044. }
  1045. }
  1046. }
  1047. ```
  1048. Environment variables:
  1049. - `${CLAUDE_PLUGIN_ROOT}` - Plugin directory path
  1050. - `${CLAUDE_PROJECT_DIR}` - Project root directory
  1051. ### Testing Plugins During Development
  1052. ```bash
  1053. # Load plugin from local directory
  1054. claude --plugin-dir ./my-plugin
  1055. # Load multiple plugins
  1056. claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
  1057. ```
  1058. ---
  1059. ## 13. Sandbox Mode & Safe Development
  1060. Claude Code can run in a restricted "sandbox" mode that prevents destructive operations while still allowing Xcode builds and simulator testing. This is ideal for:
  1061. - Learning Claude Code safely
  1062. - Reviewing AI-generated changes before applying
  1063. - Team environments where oversight is required
  1064. ### Permission Modes
  1065. | Mode | Description | Use Case |
  1066. |------|-------------|----------|
  1067. | **Plan Mode** | Read-only, no file modifications | Architecture planning, code review |
  1068. | **Normal Mode** | Asks permission for each action | Default, balanced safety |
  1069. | **Auto-Accept Mode** | Executes without confirmation | Trusted, repetitive tasks |
  1070. ### Sandbox Configuration
  1071. Create a restrictive `.claude/settings.json` that allows builds but limits writes:
  1072. ```json
  1073. {
  1074. "model": "claude-sonnet-4-5-20250929",
  1075. "permissions": {
  1076. "allow": [
  1077. "Read",
  1078. "Glob",
  1079. "Grep",
  1080. "mcp__xcodebuildmcp__discover_projects",
  1081. "mcp__xcodebuildmcp__list_schemes",
  1082. "mcp__xcodebuildmcp__list_simulators",
  1083. "mcp__xcodebuildmcp__build_sim_name_proj",
  1084. "mcp__xcodebuildmcp__build_sim_name_ws",
  1085. "mcp__xcodebuildmcp__test_sim_name_proj",
  1086. "mcp__xcodebuildmcp__test_sim_name_ws",
  1087. "mcp__xcodebuildmcp__clean",
  1088. "mcp__xcodebuildmcp__boot_simulator",
  1089. "mcp__xcodebuildmcp__install_app",
  1090. "mcp__xcodebuildmcp__launch_app",
  1091. "mcp__xcodebuildmcp__capture_logs",
  1092. "mcp__xcodebuildmcp__screenshot",
  1093. "mcp__xcodebuildmcp__swift_package_build",
  1094. "mcp__xcodebuildmcp__swift_package_test",
  1095. "Bash(git status)",
  1096. "Bash(git diff *)",
  1097. "Bash(git log *)",
  1098. "Bash(swift build *)",
  1099. "Bash(swift test *)",
  1100. "Bash(swiftlint *)",
  1101. "Bash(xcrun simctl *)"
  1102. ],
  1103. "deny": [
  1104. "Write",
  1105. "Edit",
  1106. "Bash(rm *)",
  1107. "Bash(git push *)",
  1108. "Bash(git commit *)",
  1109. "Bash(git checkout *)",
  1110. "Bash(git reset *)"
  1111. ]
  1112. }
  1113. }
  1114. ```
  1115. ### Sandbox Workflow
  1116. #### 1. Start in Plan Mode
  1117. ```bash
  1118. # Start session in Plan Mode (read-only)
  1119. claude --permission-mode plan
  1120. ```
  1121. #### 2. Let Claude Analyze and Plan
  1122. ```
  1123. "Ultrathink about how to implement the login feature.
  1124. Read the codebase, understand the architecture, and create a detailed plan.
  1125. DO NOT write any code yet."
  1126. ```
  1127. #### 3. Review the Plan
  1128. Claude will analyze your codebase and propose changes without modifying anything.
  1129. #### 4. Switch to Normal Mode for Controlled Execution
  1130. ```bash
  1131. # In session, press Shift+Tab twice to cycle to Normal Mode
  1132. # Or start a new session without --permission-mode plan
  1133. claude
  1134. ```
  1135. #### 5. Apply Changes with Approval
  1136. In Normal Mode, Claude will ask for permission before each file modification.
  1137. ### Graduated Permission Levels
  1138. #### Level 1: Full Sandbox (Read + Build Only)
  1139. ```json
  1140. {
  1141. "permissions": {
  1142. "allow": [
  1143. "Read", "Glob", "Grep",
  1144. "mcp__xcodebuildmcp__build_*",
  1145. "mcp__xcodebuildmcp__test_*",
  1146. "mcp__xcodebuildmcp__list_*",
  1147. "mcp__xcodebuildmcp__boot_simulator",
  1148. "mcp__xcodebuildmcp__capture_logs"
  1149. ],
  1150. "deny": ["Write", "Edit"]
  1151. }
  1152. }
  1153. ```
  1154. - ✅ Read all files
  1155. - ✅ Build projects
  1156. - ✅ Run tests
  1157. - ✅ Boot simulators and capture logs
  1158. - ❌ Cannot create or modify files
  1159. #### Level 2: Sandbox + Docs Writing
  1160. ```json
  1161. {
  1162. "permissions": {
  1163. "allow": [
  1164. "Read", "Glob", "Grep",
  1165. "Write(docs/*)",
  1166. "Edit(docs/*)",
  1167. "mcp__xcodebuildmcp__*"
  1168. ],
  1169. "deny": [
  1170. "Write(*.swift)",
  1171. "Edit(*.swift)",
  1172. "Write(*.json)",
  1173. "Write(*.plist)"
  1174. ]
  1175. }
  1176. }
  1177. ```
  1178. - ✅ Everything in Level 1
  1179. - ✅ Can write PRDs, specs, and documentation
  1180. - ❌ Cannot modify Swift code or config files
  1181. #### Level 3: Sandbox + Test Files
  1182. ```json
  1183. {
  1184. "permissions": {
  1185. "allow": [
  1186. "Read", "Glob", "Grep",
  1187. "Write(docs/*)",
  1188. "Write(*Tests/*.swift)",
  1189. "Write(*Tests/**/*.swift)",
  1190. "Edit(*Tests/*.swift)",
  1191. "Edit(*Tests/**/*.swift)",
  1192. "mcp__xcodebuildmcp__*"
  1193. ],
  1194. "deny": [
  1195. "Write(*/App/*)",
  1196. "Write(*/Features/*)",
  1197. "Write(*/Core/*)"
  1198. ]
  1199. }
  1200. }
  1201. ```
  1202. - ✅ Everything in Level 2
  1203. - ✅ Can write and edit test files
  1204. - ❌ Cannot modify production code
  1205. #### Level 4: Full Development (Normal)
  1206. ```json
  1207. {
  1208. "permissions": {
  1209. "allow": [
  1210. "Read", "Write", "Edit",
  1211. "mcp__xcodebuildmcp__*",
  1212. "Bash(git *)",
  1213. "Bash(swift *)"
  1214. ],
  1215. "deny": [
  1216. "Write(.env*)",
  1217. "Write(**/Secrets.swift)",
  1218. "Bash(rm -rf *)"
  1219. ]
  1220. }
  1221. }
  1222. ```
  1223. - ✅ Full development capabilities
  1224. - ❌ Cannot touch secrets or run destructive commands
  1225. ### Sandbox Slash Commands
  1226. Create sandbox-specific commands:
  1227. **`.claude/commands/sandbox-review.md`**
  1228. ```markdown
  1229. ---
  1230. description: Review code changes in sandbox mode (read-only)
  1231. allowed-tools: Read, Grep, Glob, mcp__xcodebuildmcp__build_*, mcp__xcodebuildmcp__test_*
  1232. ---
  1233. # Sandbox Code Review
  1234. Analyze the codebase in read-only mode:
  1235. 1. Read and understand the current implementation
  1236. 2. Build the project to verify it compiles
  1237. 3. Run tests to check current state
  1238. 4. Identify issues and improvements
  1239. 5. Output findings as a report
  1240. DO NOT modify any files. This is analysis only.
  1241. ```
  1242. **`.claude/commands/sandbox-build.md`**
  1243. ```markdown
  1244. ---
  1245. description: Build and test without modifying code
  1246. allowed-tools: mcp__xcodebuildmcp__*, Read
  1247. ---
  1248. # Sandbox Build & Test
  1249. Execute build and test cycle:
  1250. 1. Clean build products: `mcp__xcodebuildmcp__clean`
  1251. 2. Build for simulator: `mcp__xcodebuildmcp__build_sim_name_proj`
  1252. 3. Run all tests: `mcp__xcodebuildmcp__test_sim_name_proj`
  1253. 4. Report results
  1254. No file modifications allowed.
  1255. ```
  1256. **`.claude/commands/sandbox-run.md`**
  1257. ```markdown
  1258. ---
  1259. description: Build and run app on simulator (sandbox)
  1260. allowed-tools: mcp__xcodebuildmcp__*
  1261. ---
  1262. # Sandbox Run App
  1263. Build and launch without code changes:
  1264. 1. List simulators: `mcp__xcodebuildmcp__list_simulators`
  1265. 2. Boot iPhone 15: `mcp__xcodebuildmcp__boot_simulator`
  1266. 3. Build app: `mcp__xcodebuildmcp__build_sim_name_proj`
  1267. 4. Install: `mcp__xcodebuildmcp__install_app`
  1268. 5. Launch: `mcp__xcodebuildmcp__launch_app`
  1269. 6. Capture logs: `mcp__xcodebuildmcp__capture_logs`
  1270. Report any build errors or runtime issues.
  1271. ```
  1272. ### Using Local Settings Override
  1273. For personal sandbox preferences without affecting team settings:
  1274. **`.claude/settings.local.json`** (gitignored)
  1275. ```json
  1276. {
  1277. "permissions": {
  1278. "deny": ["Write", "Edit"]
  1279. }
  1280. }
  1281. ```
  1282. This overrides team settings to enforce sandbox mode for your local environment.
  1283. ### Sandbox Session Workflow Example
  1284. ```bash
  1285. # Terminal 1: Start Claude Code in sandbox
  1286. cd /path/to/ios-project
  1287. claude --permission-mode plan
  1288. # In Claude Code session:
  1289. > /sandbox-review
  1290. # Claude analyzes codebase, builds, tests, reports findings
  1291. > "What improvements would you suggest for the networking layer? ultrathink"
  1292. # Claude provides detailed analysis without modifying code
  1293. > "Create a detailed implementation plan for those improvements"
  1294. # Claude outputs plan to docs/
  1295. # When ready to implement, start new session:
  1296. # Terminal 2: Normal mode for implementation
  1297. claude
  1298. > "Implement step 1 from the networking improvement plan"
  1299. # Claude asks permission before each change
  1300. ```
  1301. ### Xcode Integration in Sandbox Mode
  1302. Even in full sandbox, you can:
  1303. | Action | Command | Allowed |
  1304. |--------|---------|---------|
  1305. | Build project | `mcp__xcodebuildmcp__build_sim_name_proj` | ✅ |
  1306. | Run tests | `mcp__xcodebuildmcp__test_sim_name_proj` | ✅ |
  1307. | Boot simulator | `mcp__xcodebuildmcp__boot_simulator` | ✅ |
  1308. | Install app | `mcp__xcodebuildmcp__install_app` | ✅ |
  1309. | Launch app | `mcp__xcodebuildmcp__launch_app` | ✅ |
  1310. | Take screenshot | `mcp__xcodebuildmcp__screenshot` | ✅ |
  1311. | Capture logs | `mcp__xcodebuildmcp__capture_logs` | ✅ |
  1312. | Create project | `mcp__xcodebuildmcp__create_project` | ❌ (if Write denied) |
  1313. ---
  1314. ## 14. Settings & Permissions
  1315. ### Project Settings (`.claude/settings.json`)
  1316. ```json
  1317. {
  1318. "model": "claude-sonnet-4-5-20250929",
  1319. "permissions": {
  1320. "allow": [
  1321. "mcp__xcodebuildmcp__*",
  1322. "Read",
  1323. "Write",
  1324. "Edit",
  1325. "Bash(git *)",
  1326. "Bash(swift *)",
  1327. "Bash(swiftlint *)",
  1328. "Bash(swift-format *)",
  1329. "Bash(xcodegen *)",
  1330. "Bash(pod *)",
  1331. "Bash(mint *)",
  1332. "WebFetch"
  1333. ],
  1334. "deny": [
  1335. "Read(.env*)",
  1336. "Read(**/Secrets.swift)",
  1337. "Write(.env*)",
  1338. "Bash(rm -rf *)"
  1339. ]
  1340. },
  1341. "env": {
  1342. "PROJECT_NAME": "MyApp",
  1343. "DEFAULT_SIMULATOR": "iPhone 15",
  1344. "SWIFT_VERSION": "6.0",
  1345. "IOS_DEPLOYMENT_TARGET": "17.0"
  1346. }
  1347. }
  1348. ```
  1349. ### Local Settings (`.claude/settings.local.json`)
  1350. ```json
  1351. {
  1352. "model": "claude-opus-4-5-20250929",
  1353. "env": {
  1354. "DEVELOPMENT_TEAM": "YOUR_TEAM_ID",
  1355. "CODE_SIGN_IDENTITY": "Apple Development"
  1356. }
  1357. }
  1358. ```
  1359. ### Global User Settings (`~/.claude/settings.json`)
  1360. ```json
  1361. {
  1362. "model": "claude-sonnet-4-5-20250929",
  1363. "permissions": {
  1364. "allow": [
  1365. "Bash(git *)",
  1366. "Read",
  1367. "Bash(swift *)"
  1368. ]
  1369. },
  1370. "theme": "dark",
  1371. "preferredEditor": "xcode"
  1372. }
  1373. ```
  1374. ---
  1375. ## 15. Hooks for Swift Development
  1376. Hooks are user-defined shell commands that execute at various points in Claude Code's lifecycle. They provide **deterministic control** - certain actions always happen rather than relying on the LLM.
  1377. ### Hook Events
  1378. | Event | Trigger | Use Case |
  1379. |-------|---------|----------|
  1380. | **PreToolUse** | Before tool calls (can block) | Validate commands, protect files |
  1381. | **PostToolUse** | After tool calls complete | Format code, run linters |
  1382. | **PermissionRequest** | When permission dialog shown | Auto-approve/deny |
  1383. | **UserPromptSubmit** | When user submits prompt | Pre-process input |
  1384. | **Notification** | When Claude sends notifications | Custom alerts |
  1385. | **Stop** | When Claude finishes responding | Summary, cleanup |
  1386. | **SubagentStop** | When subagent tasks complete | Post-processing |
  1387. | **PreCompact** | Before compact operation | Save context |
  1388. | **SessionStart** | When session starts/resumes | Environment setup |
  1389. | **SessionEnd** | When session ends | Cleanup, logging |
  1390. ### Configuration
  1391. Add to `.claude/settings.json` or use `/hooks` command:
  1392. ```json
  1393. {
  1394. "hooks": {
  1395. "SessionStart": [
  1396. {
  1397. "matcher": "",
  1398. "hooks": [
  1399. {
  1400. "type": "command",
  1401. "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.sh"
  1402. }
  1403. ]
  1404. }
  1405. ],
  1406. "PostToolUse": [
  1407. {
  1408. "matcher": "Write|Edit",
  1409. "hooks": [
  1410. {
  1411. "type": "command",
  1412. "command": "jq -r '.tool_input.file_path' | { read f; [[ \"$f\" == *.swift ]] && swiftlint lint --path \"$f\" --quiet; }"
  1413. }
  1414. ]
  1415. }
  1416. ],
  1417. "PreToolUse": [
  1418. {
  1419. "matcher": "Edit|Write",
  1420. "hooks": [
  1421. {
  1422. "type": "command",
  1423. "command": "python3 -c \"import json,sys; d=json.load(sys.stdin); p=d.get('tool_input',{}).get('file_path',''); sys.exit(2 if '.env' in p or 'Secrets.swift' in p else 0)\""
  1424. }
  1425. ]
  1426. }
  1427. ]
  1428. }
  1429. }
  1430. ```
  1431. ### Matcher Patterns
  1432. | Pattern | Matches |
  1433. |---------|---------|
  1434. | `Write` | Exactly "Write" tool |
  1435. | `Write\|Edit` | Write OR Edit tools |
  1436. | `mcp__xcodebuildmcp__*` | All XcodeBuildMCP tools |
  1437. | `*` or `""` | All tools |
  1438. ### Hook Return Codes
  1439. For **PreToolUse** hooks:
  1440. - Exit `0`: Continue with tool call
  1441. - Exit `2`: Block tool call, provide feedback to Claude
  1442. For **PermissionRequest** hooks, output JSON:
  1443. ```json
  1444. {
  1445. "decision": "approve",
  1446. "reason": "Documentation file auto-approved",
  1447. "suppressOutput": true
  1448. }
  1449. ```
  1450. ### Environment Variables
  1451. | Variable | Description |
  1452. |----------|-------------|
  1453. | `$CLAUDE_PROJECT_DIR` | Project root directory |
  1454. | `${CLAUDE_PLUGIN_ROOT}` | Plugin directory (for plugin hooks) |
  1455. ### Hook Scripts
  1456. **`.claude/hooks/session-start.sh`**
  1457. ```bash
  1458. #!/bin/bash
  1459. PROJECT_NAME=$(basename "$(pwd)")
  1460. SWIFT_VERSION=$(swift --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+' | head -1)
  1461. XCODE_VERSION=$(xcodebuild -version 2>/dev/null | head -1)
  1462. echo "🚀 Starting $PROJECT_NAME session" >&2
  1463. echo "📱 Swift $SWIFT_VERSION | $XCODE_VERSION" >&2
  1464. # Check for common issues
  1465. if ! command -v swiftlint &> /dev/null; then
  1466. echo "⚠️ SwiftLint not installed" >&2
  1467. fi
  1468. # Check if simulator is booted
  1469. if ! xcrun simctl list devices booted | grep -q "Booted"; then
  1470. echo "💡 No simulator running. Use /run-app to boot one." >&2
  1471. fi
  1472. ```
  1473. **`.claude/hooks/post-swift-edit.sh`**
  1474. ```bash
  1475. #!/bin/bash
  1476. # Read file path from stdin JSON
  1477. FILE=$(jq -r '.tool_input.file_path // empty')
  1478. if [[ "$FILE" != *.swift ]]; then
  1479. exit 0
  1480. fi
  1481. # Run SwiftLint on the edited file
  1482. if command -v swiftlint &> /dev/null && [ -f ".swiftlint.yml" ]; then
  1483. swiftlint lint --path "$FILE" --quiet 2>&1 | head -5 >&2
  1484. fi
  1485. # Run swift-format check
  1486. if command -v swift-format &> /dev/null; then
  1487. swift-format lint "$FILE" 2>&1 | head -3 >&2
  1488. fi
  1489. ```
  1490. **`.claude/hooks/file-protection.sh`** (PreToolUse)
  1491. ```bash
  1492. #!/bin/bash
  1493. # Block edits to sensitive files
  1494. FILE=$(jq -r '.tool_input.file_path // empty' < /dev/stdin)
  1495. PROTECTED_PATTERNS=(
  1496. ".env"
  1497. "Secrets.swift"
  1498. "GoogleService-Info.plist"
  1499. ".git/"
  1500. "Podfile.lock"
  1501. )
  1502. for pattern in "${PROTECTED_PATTERNS[@]}"; do
  1503. if [[ "$FILE" == *"$pattern"* ]]; then
  1504. echo "🛡️ Protected file: $FILE" >&2
  1505. exit 2 # Block the operation
  1506. fi
  1507. done
  1508. exit 0 # Allow the operation
  1509. ```
  1510. ### Setup via `/hooks` Command
  1511. ```bash
  1512. # Interactive hook configuration
  1513. /hooks
  1514. # Select event type (e.g., PostToolUse)
  1515. # Add matcher (e.g., "Write|Edit")
  1516. # Add hook command
  1517. # Choose storage location (User/Project)
  1518. ```
  1519. Make hooks executable:
  1520. ```bash
  1521. chmod +x .claude/hooks/*.sh
  1522. ```
  1523. ---
  1524. ## 16. Complete Project Structure
  1525. ```
  1526. MyiOSApp/
  1527. ├── .claude/
  1528. │ ├── commands/ # Project slash commands
  1529. │ │ ├── build.md
  1530. │ │ ├── test.md
  1531. │ │ ├── run-app.md
  1532. │ │ ├── create-view.md
  1533. │ │ ├── implement-feature.md
  1534. │ │ ├── create-prd.md
  1535. │ │ ├── generate-spec.md
  1536. │ │ ├── sandbox-build.md
  1537. │ │ └── sandbox-review.md
  1538. │ ├── agents/ # Project subagents
  1539. │ │ ├── ios-architect.md
  1540. │ │ ├── swift-reviewer.md
  1541. │ │ └── swiftui-specialist.md
  1542. │ ├── skills/ # Agent Skills
  1543. │ │ ├── ios-testing/
  1544. │ │ │ └── SKILL.md
  1545. │ │ └── swiftui-components/
  1546. │ │ ├── SKILL.md
  1547. │ │ └── templates/
  1548. │ ├── output-styles/ # Custom output styles
  1549. │ │ └── ios-mentor.md
  1550. │ ├── hooks/ # Automation hooks
  1551. │ │ ├── session-start.sh
  1552. │ │ ├── post-swift-edit.sh
  1553. │ │ └── file-protection.sh
  1554. │ ├── settings.json # Team settings (committed)
  1555. │ └── settings.local.json # Personal settings (gitignored)
  1556. │ └── settings.sandbox.json # Sandbox mode template
  1557. ├── .mcp.json # MCP server configuration
  1558. ├── CLAUDE.md # Main project context
  1559. ├── docs/
  1560. │ ├── PRD.md # Product Requirements Document
  1561. │ ├── ARCHITECTURE.md # Architecture decisions
  1562. │ ├── ROADMAP.md # Development roadmap
  1563. │ ├── specs/ # Feature specifications
  1564. │ │ ├── template.md
  1565. │ │ ├── 001-authentication.md
  1566. │ │ └── 002-dashboard.md
  1567. │ └── tasks/ # Task breakdowns
  1568. │ └── authentication-tasks.md
  1569. ├── MyApp/
  1570. │ ├── App/
  1571. │ │ └── MyAppApp.swift
  1572. │ ├── Features/
  1573. │ │ ├── Authentication/
  1574. │ │ │ ├── CLAUDE.md # Feature-specific context
  1575. │ │ │ ├── Views/
  1576. │ │ │ └── ViewModels/
  1577. │ │ └── Dashboard/
  1578. │ ├── Core/
  1579. │ │ ├── Extensions/
  1580. │ │ ├── Services/
  1581. │ │ └── Networking/
  1582. │ └── Resources/
  1583. ├── MyAppTests/
  1584. ├── MyAppUITests/

Lines 2,001–2,194 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.