# Cursor Agent for Swift and iOS: A Practical Guide

URL: https://agentvera.dev/en/blog/cursor-agent-for-swift/ · Published: 2026-11-01

Learn to run Cursor Agent in a Swift and iOS project: AGENTS.md setup, example prompts, XCTest verification, and SwiftUI/UIKit pitfalls.

**In short:**

- Set up AGENTS.md or .cursor/rules with exact xcodebuild, swift test, and SwiftLint commands before running cursor-agent.
- Use small, testable steps and review diffs because Swift and iOS work can break on @MainActor, .pbxproj, and iOS availability.
- Run parallel Cursor Agent instances in git worktrees with AgentVera for safe, reviewable Swift work.

Run `cursor-agent` inside your Swift or iOS project directory and treat it as a senior pair programmer that already knows Xcode, SwiftUI, UIKit, and Swift Package Manager. The agent works best when you put build, test, and lint commands plus project-specific rules in AGENTS.md or .cursor/rules, then drive it in small, testable changes. This guide covers setup, a working loop, testing, and pitfalls for Swift and iOS work with [Cursor Agent](/en/agents/cursor-agent/).

## Why a terminal agent fits Swift and iOS

Cursor Agent is a terminal agent, so it can read Swift source, edit files, and then run the same commands an iOS developer runs: `xcodebuild`, `swift test`, `swiftlint`, and `git diff`. That closes the loop between writing code and verifying it. Swift and iOS projects have unusually precise failure modes: `@MainActor` isolation, `some View` opaque types, `Codable` synthesis, simulator destinations, and the notoriously brittle Xcode project file. A terminal agent that can run the compiler and test runner is more useful than a chat-only suggestion, because it sees compiler errors and XCTest failures in context and can fix them in the next step.

For SwiftUI and UIKit work specifically, the agent can handle repetitive but context-heavy tasks such as converting a completion-handler API to async/await, adding SwiftUI previews, or migrating a UITableView data source to a diffable data source. It is not a replacement for Xcode, but it reduces the round trips between thinking, typing, and waiting for a build.

## Configure AGENTS.md for your Xcode project

The most important setup step is to give `cursor-agent` project-specific instructions. Cursor Agent reads AGENTS.md and .cursor/rules. For a Swift and iOS project, those files should specify exact build, test, and lint commands, the folder layout, and rules that prevent common Swift mistakes. If the agent has to guess the simulator destination or the scheme, it will waste turns or generate commands that fail.

Here is a realistic AGENTS.md for a mixed SwiftUI/UIKit app:

```markdown
# AGENTS.md

## Commands
- Build: `xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' build`
- Test: `xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' test`
- Swift package tests: `swift test` (run from the directory containing Package.swift)
- Lint: `swiftlint lint --strict`

## Project layout
- `MyApp/` — SwiftUI views, UIKit screens, models, and services
- `MyAppTests/` — XCTest unit tests
- `MyAppUITests/` — UI tests
- `Packages/` — local Swift packages

## Rules
- Use `@MainActor` for all UI code and view models that publish to SwiftUI.
- Do not edit `MyApp.xcodeproj/project.pbxproj` by hand; ask me to add files in Xcode.
- Prefer `async/await` over completion handlers and Combine for new networking code.
- Keep all generated code compatible with iOS 16 unless told otherwise.
- Run `swiftlint lint --strict` after every change and fix warnings.
- Add XCTest coverage for new model and view model logic.
```

Write the same file to .cursor/rules if your project already uses that directory. The commands block prevents the agent from inventing a destination like a generic simulator; the project layout keeps new test files in the right target; the rules cut down on the two most common Swift agent mistakes: touching .pbxproj and forgetting `@MainActor`. Start `cursor-agent` from the project root after saving these files. For a walkthrough of the CLI workflow, see [How to use Cursor CLI: a step-by-step guide](/en/blog/how-to-use-cursor-cli/).

## The plan-change-test-diff loop

Use the same loop you would use with a human pair programmer: plan, make one small change, run the tests, review the diff, then repeat. Do not ask for a large rewrite in one turn. In Swift, a large rewrite can break type inference, actor isolation, and the Xcode project at the same time, which makes the follow-up turn harder.

Start with a planning prompt:
List the files you will touch, the tests you will add or change, and the build commands you will run. Do not write code yet.

Then make the change in one focused step. A few example prompts that work well for Swift and iOS:
- Create an XCTest for `APIClient.fetchPosts()` using URLProtocol or a mock URLSession, with async/await. Put the test file in MyAppTests.
- Refactor this UITableView data source into a diffable data source. Keep the existing cell configuration and row selection.
- Add SwiftUI previews for `ProfileView` with sample models and a fixed frame, without changing production code.
- Find all force unwraps in `MyApp/` and replace them with safe unwrapping, then run the unit tests.

After each change, ask the agent to run the test command from AGENTS.md and paste the full output. Then inspect `git diff` yourself. In Swift, pay attention to changes in `@MainActor` annotations, new `weak` references in closures, and any diff in `project.pbxproj` that you did not ask for.

## Strong areas and red flags in Swift and iOS

Cursor Agent handles several Swift and iOS tasks well:
- Converting callback-based networking code to `async/await` using continuations.
- Extracting a SwiftUI view into smaller views with `@ViewBuilder` or `ForEach`.
- Adding `Codable` conformance to model types and writing round-trip tests.
- Writing XCTest cases for view models using mock services.
- Updating Package.swift dependencies or local package structure.
- Generating SwiftUI previews and sample data.

Places to watch closely:
- The Xcode project file. Any direct edit to `project.pbxproj` can break the project. If the agent needs to add a new source file, prefer Swift Package Manager or ask it to list the file for you to add in Xcode.
- Concurrency and `@MainActor`. The agent may create an `ObservableObject` view model that publishes from a background queue or omit `@MainActor` from a UIView subclass that mutates UI.
- iOS availability. The agent may use `NavigationStack`, `ContentUnavailableView`, or newer `UIColor` APIs without checking the deployment target.
- UIKit memory management. Watch for `[weak self]` missing in escaping closures, especially in network callbacks and notification observers.
- SwiftUI view identity and `ForEach` IDs. The agent can generate an id from an unstable property, causing animation glitches.

## Verify with xcodebuild and swift test

Do not merge an agent change until you have both compile output and test output. The exact commands belong in AGENTS.md, but verify them yourself early on.

| Command | What it verifies |
|---|---|
| `xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' build` | The app target compiles and links |
| `xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' test` | Unit tests and UI tests pass in the simulator |
| `swift test` | Swift package logic passes without the Xcode project |
| `swiftlint lint --strict` | Style rules catch force unwraps, trailing whitespace, and long lines |

If a test fails, paste the relevant XCTest assertion and the failing line back to the agent. Ask for the minimal fix and have it rerun the same test command. Also run `git diff --check` to catch whitespace errors and `git status` to see which files changed. Before accepting a larger change, build the app in Xcode once; sometimes the agent’s command-line build passes while the Xcode GUI shows a stale scheme or signing issue.

## Parallel cursor-agent work with AgentVera

For running several cursor-agent instances on one Swift project, the relevant features in [AgentVera](/en/blog/best-tools-parallel-ai-coding-agents/) are parallel git worktrees, automatic code review, and checkpoints. Because an Xcode project has a shared `project.pbxproj` and generated files, running agents in the same directory risks overwriting each other’s changes; separate worktrees let each agent edit independently. After each turn, a second model reviews the Swift diff and links findings to file:line, which catches missed `@MainActor` or retain cycles. Checkpoints let you undo a bad view model refactor in one click. These three reduce the cost of parallel Swift work more than raw terminal tabs.

## Keep the loop tight for Swift

Cursor Agent becomes a reliable Swift and iOS coding partner when you give it exact build commands and Swift-specific rules, keep changes small, and always verify with tests and diffs. Use AGENTS.md or .cursor/rules as the source of truth, let the agent run `xcodebuild` and `swift test`, and treat every change as a patch to review before accepting. With that loop, it handles the repetitive and type-heavy parts of SwiftUI, UIKit, and SPM work.

## Frequently asked questions

**How do I start Cursor Agent in a Swift and iOS project?** Run cursor-agent in the project root after creating AGENTS.md or .cursor/rules with the Xcode build, test, and lint commands. Then ask it to plan a small change, run the tests, and show the diff.

**Can Cursor Agent edit Xcode project files safely?** It can edit project.pbxproj, but that file is brittle and manual edits often break the project. Tell the agent in AGENTS.md not to modify it; ask it to describe new files and add them in Xcode yourself, or use Swift Package Manager.

**Is Cursor Agent good for SwiftUI and UIKit work?** Yes, it handles view composition, view models, Codable models, async/await conversions, and XCTest well. Watch closely for missing @MainActor, iOS availability checks, and retain cycles in UIKit closures.

**How do I test Swift code changes made by Cursor Agent?** Use the exact xcodebuild test command with a simulator destination, or swift test for packages. Review the test output and git diff, paste failures back to the agent, and rerun the same command before accepting.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/