Gemini CLI for Swift and iOS: A Practical Guide

Gemini CLI is a terminal coding agent you start with gemini in a project folder. For Swift and iOS work, it can read and edit Swift files, write tests, and run Xcode or Swift Package Manager commands, but it needs explicit project context to avoid fighting Xcode’s project format. This guide covers setup, GEMINI.md, a safe working loop, and verification for SwiftUI, UIKit, and SPM projects. See Gemini CLI for the agent itself.

What makes Gemini CLI useful in Swift and iOS projects

Gemini CLI suits Swift and iOS work because it operates directly in the terminal where xcodebuild, swift test, and swiftlint already run. It can parse build errors, open the relevant Swift file, and propose a fix without switching tools. That tight loop matters in iOS because compile times and simulator launches make every unnecessary round-trip expensive. The agent also reads multiple files in one pass, so it can keep protocols, extensions, and SwiftUI preview providers in mind while editing. For async/await, actors, and @MainActor, it can apply consistent concurrency rules if you state them once in GEMINI.md.

Set up GEMINI.md with exact build, test, and lint commands

Start by running gemini in the repository root, next to the .xcodeproj or .xcworkspace and Package.swift if you have one. Create a GEMINI.md that gives the agent exact build, test, and lint commands, plus folder conventions and rules that prevent common Swift and iOS mistakes. The example below works for a SwiftUI/UIKit app with a local Swift package.

# GEMINI.md

## Commands
Build: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' build
Test: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' test
Package tests: swift test
Lint: swiftlint --strict

## Layout
- MyApp/ - app target, SwiftUI and UIKit files
- MyAppTests/ - XCTest unit tests
- Packages/Shared - local Swift package

## Rules
- Use async/await, not completion handlers.
- Keep project.pbxproj changes minimal; prefer folder references or XcodeGen if adding files.
- Run tests after each change. Do not commit without passing.
- For SwiftUI previews, keep sample data in #Preview.
- Deployment target is iOS 17; do not use newer APIs without asking.

Update simulator names to match your installed runtimes, and keep the commands in sync with your CI if you have one. The GEMINI.md is read every time the agent starts, so it is the most important file for reproducible agent work. For more on setting up the agent itself, see How to use Gemini CLI: a step-by-step guide.

A small edit-test-review loop for SwiftUI and UIKit

Use a plan-first loop: ask the agent to explore the relevant files and state its intended change before editing. Then let it make one small change, run the relevant tests, and show you a diff. Review the diff in Xcode or with git diff before moving on. This avoids the agent rewriting a whole screen flow to fix a layout warning. Example prompts for typical Swift and iOS tasks:

• “Read the login flow in LoginView.swift and LoginViewModel.swift. Find all uses of completion handlers and propose an async/await refactor plan before editing.”
• “Add a SwiftUI view that lists Core Data items using @FetchRequest and supports swipe to delete. Add a matching XCTest for the view model.”
• “Fix this failing test: [paste test]. Keep the existing public API and explain the root cause in two sentences.”
• “Convert the UIKit table view data source in ListViewController.swift to a diffable data source without changing the cell class.”
• “Run swift test, then fix only the first two failures and paste the diff.”

Where Gemini CLI shines, and common Swift and iOS pitfalls

Gemini CLI handles well: parsing JSON into Codable structs and generating tests, writing SwiftUI list and form views with sample data for #Preview, converting UIKit table/collection view data sources to diffable data sources, adding a local SPM package and moving shared code, writing XCTest cases for view models and network layers with mocked URLProtocol, and applying concurrency annotations.

Watch it closely around these Swift and iOS pitfalls. Xcode project file edits: the agent may edit project.pbxproj incorrectly, causing merge conflicts or a broken project; prefer folder references or XcodeGen. Storyboard and XIB changes: those XML diffs are hard to review and easy to break, so keep UI in code unless you intentionally ask for storyboard work. Strict concurrency: the agent may miss @MainActor, Sendable, or actor isolation, or it may overuse @unchecked Sendable; review every concurrency annotation carefully. SwiftUI previews: it may use iOS 17-only APIs while your deployment target is lower, so state the target in GEMINI.md. Simulator destination mismatches: if the agent guesses the wrong simulator name, build and test commands fail; always define the exact destination in GEMINI.md. Async tests: XCTest expectations mixed with async/await can hang; ask for @MainActor test methods and meaningful assertions.

Verify changes with XCTest, xcodebuild, and swift test

Have the agent run tests itself and paste the last 30 lines of output, not just say “passed.” Use the exact command from GEMINI.md. For UI tests, ask it to run only the relevant test class to avoid long runs. For SPM packages, swift test is usually enough. Occasionally build with SWIFT_STRICT_CONCURRENCY=complete to surface data-race warnings, but do not ask the agent to fix all of them at once.

After a bug fix, ask for a regression test before considering the task done. Review generated tests for meaningful assertions, not just XCTAssertNotNil. For a more detailed debugging workflow, see How to debug code with AI: a practical workflow.

Run several agents on one iOS project with AgentVera

AgentVera is a desktop app that runs real coding agent CLIs side by side in one window. For Swift and iOS, the most useful parts are parallel agents in separate git worktrees, so one agent can work on a SwiftUI feature while another refactors an SPM package without overwriting files. Automatic code review at the end of each turn catches retain cycles, missing @MainActor, and broken XCTest expectations before you merge. Checkpoints let you undo a bad view-model refactor in one click and replay the session step by step. Token budgets keep a slow Xcode test loop from consuming the whole day, stopping at the cap while preserving the conversation.

Use Gemini CLI like a fast, careful pair programmer

With a specific GEMINI.md, plan-first small steps, and test-after-every-change discipline, Gemini CLI becomes a practical pair programmer for Swift and iOS. The main skill is giving it enough project context up front and reviewing its diffs as carefully as you would review a teammate’s. Use the agent for repetitive, well-scoped work, and keep Xcode open for Interface Builder changes and final UI verification.