6 tips to master Claude Agent in Xcode 26.3

A week with Claude Agent in Xcode

Xcode 26.3 brought Claude Agent directly into the IDE. After more than a week of daily use on a real iOS project (Keepio), here are 6 tips to unlock its full potential.

Tip 1: Update the bundled Claude model

By default, Xcode ships with a Claude Code client version frozen at the Release Candidate prep date. The catch is that, in the meantime, Anthropic keeps shipping updates.

On the current RC, Xcode uses version 2.1.14 while the CLI is at 2.1.37, the difference between Claude Opus 4.5 and Claude Opus 4.6.

The fix is straightforward: copy the CLI binary to Xcode's internal path.

cp $(which claude) ~/Library/Developer/Xcode/CodingAssistant/Agents/Versions/26.3/claude

Restart Xcode and you are good to go. It is not officially supported by Apple, but it works without issue.

Tip 2: Make your Claude Code plugins available in Xcode

If you already use Claude Code in CLI with plugins (like my iOS plugins), you can expose them in Xcode through a symbolic link.

ln -s ~/.claude/commands ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/commands

After a restart, the plugins show up in autocompletion when you type /.

What works and what does not: markdown instructions, arguments and core tools are supported. Specialised sub-agents and Claude Code hooks are not, in the Xcode context. In practice, about 80% of plugins work, which is already significant.

Tip 3: Add a custom MCP (and the simulator trap)

To extend the agent's capabilities (simulator screenshots, custom commands), you can build your own MCP server and configure it in Xcode.

Configuration goes into Xcode's claude.json, in the projects block. Three critical points:

• The type must be stdio
• hasTrustDialogAccepted must be true
• The command path must be absolute (Xcode does not load your .zshrc)

The trap: simctl launch is not Xcode Run

This is the most surprising finding. When you click Xcode's Run button, it performs 6 operations:

1. Build with code signing and entitlements
2. Install on the simulator with full configuration
3. Set up environment variables
4. Attach the debugger
5. Configure containers (CloudKit, Keychain, App Groups)
6. Launch

The simctl launch command? It only launches the binary. Nothing else.

Consequence: apps using CloudKit or Keychain crash systematically with simctl. It is a known gap in Apple's tooling, and there is no CLI command that reproduces the Run button.

Tip 4: Watch out for the @ tag

An intermittent RC bug: when you tag a file with @ and paste a screenshot in the same message, the prompt can get truncated. The agent only receives part of the message.

Workaround: avoid combining tag and screenshot in a single send. Send them separately.

Tip 5: Preview vs Simulator, what the agent actually sees

The Claude agent works with SwiftUI previews, not the simulator. It can capture screenshots of the preview and verify visual rendering.

What it cannot do:

• See a bug that only shows up on the simulator
• Test a full navigation flow
• Interact with the simulator (taps, scroll, navigation)

The reflex to build: if the bug is simulator-specific, describe it clearly in the prompt, stating the expected behaviour against the actual one.

Tip 6: The adaptive CLAUDE.md

If you use Claude both in CLI and in Xcode, you do not need the same instructions. In CLI, the agent can do git and run scripts. In Xcode, it has access to previews and the build but not the terminal.

The fix: leverage the CLAUDE_CONFIG_DIR variable to detect the environment and load the right instructions.

Three layers of instructions

1. CLAUDE.md (root): detects the environment and redirects to the right file
2. CLAUDE-XCODE.md or CLAUDE-CLI.md: context-specific instructions
3. CLAUDE.md per SPM module (optional): instructions for each module

It is a 10-minute setup that radically improves the quality of the agent's responses, especially on large multi-module projects.

Verdict after a week

Claude Agent in Xcode is a genuinely promising V1.

For prototyping, SwiftUI generation or refactoring, it is already excellent. The agent quickly picks up your code habits and reproduces them faithfully.

For complex apps with CloudKit or end-to-end testing, we are not there yet. But progress will come.

The key is to know the limits and the tricks so you can get the best out of it today.