Yes, you can use Claude Code for iOS development, even though it is a terminal agent and your iOS work lives in Xcode. Claude Code edits your Swift files and runs your builds and tests from the command line with xcodebuild, while you keep Xcode open for running the app, SwiftUI previews, and debugging. They are not competing editors; they are two tools with a clean division of labor. The trick is setting it up so the agent can verify its own work instead of writing code blind.
This guide covers the setup that makes that reliable: how the two tools split the job, how to let the agent build and test from the CLI, how a CLAUDE.md keeps its output consistent with your project, and the slash commands, hooks, and MCP servers that turn it from a chat box into part of your workflow. It also covers the gotchas that are specific to Xcode projects.
On this page
- Does Claude Code even work for iOS?
- The core setup
- Give it a CLAUDE.md
- Let it build and test from the CLI
- Keep running and previews in Xcode
- Slash commands, hooks, and MCP
- A realistic workflow
- Xcode-specific gotchas
- FAQ
Does Claude Code even work for iOS?
It does, and the confusion comes from expecting it to be an editor like Xcode or a plugin inside it. Claude Code is a terminal agent. It reads and writes the files in your repository and runs shell commands, which is all it needs, because a SwiftUI project is just Swift files in a folder and Xcode is one way to look at them.
The mental model that works is a division of labor. Claude Code owns the code: writing views, refactoring, wiring up a feature, running tests. Xcode owns the runtime: launching the app in the simulator, rendering SwiftUI previews, stepping through the debugger, and inspecting the view hierarchy. You run both at once, the agent in a terminal and Xcode alongside it, and let each do the half it is good at.
The core setup
Install Claude Code and start it from the root of your project, the folder that contains your .xcodeproj or .xcworkspace:
cd ~/Developer/MyApp
claudeThat is the entire setup to get going. Claude Code now sees your whole project and can edit any file in it. Keep Xcode open on the same folder. Because both are looking at the same files on disk, an edit the agent makes shows up in Xcode immediately, and a change you make in Xcode is visible to the agent on its next read. There is no sync step and no plugin.
The one habit worth forming early is to work on a branch and commit often, so the agent's changes are easy to review and easy to undo. That is good practice with any agent, and it matters more in a project where a bad edit to a shared file can break the build.
Give it a CLAUDE.md
Out of the box, an agent writes the average SwiftUI it has seen, which mixes years of patterns. A CLAUDE.md file at your repository root fixes that: Claude Code reads it automatically and treats it as the project's house rules. Tell it which state pattern you use, that networking goes through your client, that strings and assets are typed, and it stops guessing.
# CLAUDE.md
- State: `@Observable` + `@State`, never `ObservableObject` / `@Published`.
- Networking: all requests through `APIClient.shared.send(_:)`.
- Assets and strings: typed `Asset` and `L10n`, never string literals.
- Tests: Swift Testing (`@Test`, `#expect`), not XCTest.This is the single highest-value thing you can add, and it is worth keeping short and specific. For the full treatment, including how to make one file serve Claude Code, Cursor, and Codex at once, see AGENTS.md for iOS.
Let it build and test from the CLI
This is what separates a useful setup from a frustrating one. If the agent cannot build, it writes code it has no way to check, and you become its compiler. Give it xcodebuild and it verifies its own work.
Building and testing an iOS project from the command line looks like this:
# Build for the simulator
xcodebuild -scheme MyApp \
-destination 'platform=iOS Simulator,name=iPhone 16' build
# Run the test suite
xcodebuild test -scheme MyApp \
-destination 'platform=iOS Simulator,name=iPhone 16'xcodebuild's output is famously noisy, so pipe it through a formatter like xcbeautify to make failures readable:
xcodebuild test -scheme MyApp \
-destination 'platform=iOS Simulator,name=iPhone 16' | xcbeautifyTell the agent, in your CLAUDE.md, to run the build or the tests after making changes. Now the loop closes: it writes code, builds, reads the errors, and fixes them, the same loop you run by hand, without waiting on you.
Keep running and previews in Xcode
There is a clean line for what stays in Xcode. Anything visual or interactive: launching the app, watching a SwiftUI preview re-render, using the debugger and breakpoints, inspecting the view hierarchy, and profiling in Instruments. The agent cannot see pixels, so it should not be the one deciding whether a layout looks right.
In practice you keep Xcode running the app in the simulator while the agent edits code. When it changes a view, you glance at Xcode to see the result, and when something looks wrong you tell the agent what you see. It handles the code, you handle the judgment about how the running app looks and feels. That split plays to both tools' strengths instead of forcing one to do the other's job.
Slash commands, hooks, and MCP
Once the basics work, three features move Claude Code from a chat box to part of your toolchain.
Custom slash commands are reusable prompts saved as markdown files in .claude/commands/. A /new-feature command that describes how a feature should be structured in your app, or a /review command that runs your checklist, saves you from retyping the same instructions. You invoke them by name in the session.
Hooks run shell commands automatically at points in the agent's work, defined in your settings. A common one is formatting or linting after every edit: run swift-format or SwiftLint on a file the moment the agent writes it, so style never drifts and you never ask for it. Hooks are deterministic, so they enforce rules the prompt might forget.
MCP servers let the agent reach external tools and data through a standard protocol, your issue tracker, a documentation source, a database. For iOS work the most useful ones connect the agent to the context it would otherwise be blind to, so it can read a ticket or check a schema without you pasting it in.
None of these are required to start, but each removes a recurring bit of friction once the core loop is working.
A realistic workflow
Putting it together, building a feature looks like this. Xcode is open and running the app in the simulator. You start Claude Code in a terminal beside it and describe the feature. It reads the relevant files, writes the new view and its model following your CLAUDE.md, and runs xcodebuild to confirm it compiles. A lint hook cleans up formatting as it goes.
You switch to Xcode, which has hot-reloaded the change, and look at the result. If the layout is off, you say so, and the agent adjusts the code. When the behavior is right, you ask it to write tests, which it runs with xcodebuild test until they pass. Then you review the diff and commit. The agent never had to see the screen, and you never had to write the boilerplate. Each did its half.
Xcode-specific gotchas
A few things are specific to Xcode projects and worth knowing up front.
- The
.xcodeprojis not friendly to edit. Theproject.pbxprojfile inside it is a dense, machine-managed format, and agents can corrupt it when adding files or targets. Prefer adding files through Xcode, or use a project setup where the file list is generated, so the agent is editing Swift, not the project file. - Merge conflicts in
pbxprojare painful. If both you and the agent add files, that file conflicts in ugly ways. Small, frequent commits and adding files one source at a time keep it manageable. - Builds are slow.
xcodebuildis much slower than a web project's build, so an agent that builds after every tiny edit will feel sluggish. Have it build at meaningful checkpoints, not on every line. - Pick a stable simulator destination. Pin the
-destinationto a simulator you know exists on your machine, otherwise builds fail with a confusing device-not-found error rather than a code error.
FAQ
Can Claude Code be used for iOS and SwiftUI development?
Yes. Claude Code is a terminal agent that edits your Swift files and runs builds and tests with xcodebuild, while you keep Xcode open for running the app, previews, and debugging. The two work side by side on the same project files.
Does Claude Code work inside Xcode?
It is not an Xcode plugin. It runs in a terminal alongside Xcode, editing the same files on disk. Both tools see changes immediately because there is no separate sync, so you run them together rather than one inside the other.
How does Claude Code build and test an iOS project?
Through xcodebuild on the command line, targeting a simulator destination. Piping the output through a formatter like xcbeautify makes failures readable. Telling the agent to build or test after changes lets it catch and fix its own compile errors.
Do I still need Xcode if I use Claude Code?
Yes. Xcode owns everything visual and interactive: running the app, SwiftUI previews, the debugger, the view hierarchy, and Instruments. Claude Code owns the code editing and CLI builds. Neither replaces the other.
How do I keep Claude Code writing consistent SwiftUI?
Add a CLAUDE.md at your repo root listing your conventions, the state pattern you use, your networking client, typed assets and strings, your testing framework. Claude Code reads it automatically and follows it, which stops the drift between old and new SwiftUI patterns.
What are the biggest pitfalls with Claude Code on an Xcode project?
The .xcodeproj file is machine-managed and easy to corrupt, builds are slow so building on every edit drags, and simulator destinations must be pinned to a device that exists. Add files through Xcode, build at checkpoints, and commit often on a branch.
Spaceport generates iOS projects that are ready for this workflow on the first build. Every project ships with a CLAUDE.md, a shared AGENTS.md, Cursor rules, and open-source Swift skill packs, plus typed Asset and L10n constants and wrapper singletons, so Claude Code writes consistent SwiftUI from the first prompt instead of learning your conventions the hard way. From an indie iOS dev, for indie iOS devs.