xcode-mods

Xcode's build, tests, console and SwiftUI previews inside Claude Code, built on the headless Xcode MCP server.

One Claude Code plugin that adds:

• a toolbar band above the prompt (scheme ▸ destination, activity, problem counters);
• an Xcode pane with Build · Run · Tests tabs;
• a Canvas pane that shows SwiftUI #Preview snapshots.

It picks up Claude's own Xcode tool calls too. When Claude builds, runs tests, launches the app or renders a preview, the result appears in the pane.

Requirements

• Xcode 27 or later with the MCP server in headless mode
• Claude Code 2.1.286 or later (mods support)
• To see previews in the terminal: a terminal with the kitty graphics protocol, such as Ghostty. The Claude desktop app works too.

Setup

1. Turn on Xcode's headless MCP server (once):

   copy

   sudo xcrun mcp-server enable
   xcrun mcp-server status
   

2. Add the server to Claude Code. The mods expect it to be named xcode:

   copy

   claude mcp add --scope user xcode -- xcrun mcpbridge
   

3. Allow the mods' Xcode calls in ~/.claude/settings.json. Without this rule, every build or refresh asks for permission:

   copy

   {
     "permissions": {
       "allow": ["mcp__xcode"]
     }
   }
   

4. Install the plugin:

   copy

   /plugin marketplace add artemnovichkov/xcode-mods
   /plugin install xcode-mods@xcode-mods
   

Open Claude Code in a folder with an .xcodeproj or .xcworkspace (up to 3 levels deep). The band appears above the prompt. In other folders the plugin stays hidden and doesn't register any commands.

Usage

Toolbar band

The band above the prompt works like Xcode's toolbar:

 Sandbox ▸ iPhone 17 Pro │ ✓ Build Succeeded 1.4s · 14:02 │ ⚠1 ✗2

• Scheme ▸ destination. Pickers; a change switches them in Xcode too.
• Activity. What runs now (◐ Building 3s · Compile ContentView.swift, ◐ Testing, ◐ Launching, ● Running Sandbox), or the last result with its time (✓ Build Succeeded, ✗ Tests Failed, ■ Sandbox stopped).
• Counters. ⛔ errors, ⚠ warnings, ✗ failed tests. Click one to open the matching tab.

The band also shows Claude's own builds, test runs and launches.

Notifications

A toast pops up in the top right corner when an action ends, whether you or Claude started it:

• Build Succeeded · 2 warnings, Build Failed · 3 errors
• Tests Passed · 12, Tests Failed · 2 failed
• Run Failed
• Preview ready: /preview to show, when the window is too narrow to open the Canvas pane by itself

Build & Issues

Live progress while the build runs, then errors and warnings. Click a file name to open that line in Xcode.

Keys: b build · x send the issues to Claude to fix

Tests

Tests are grouped by target and suite, with failures first and their messages shown inline. Click a test to run only that test.

Keys: t run all · f rerun failed · l reload the list · x ask Claude to fix the failures

Run & Console

The app's stdout and OSLog stream in while it runs.

Keys: r run · s stop · e errors only · k clear · x ask Claude about the console

SwiftUI Preview

Keeps the last 10 snapshots. Once you have rendered a preview, it re-renders after Claude edits a Swift file that contains #Preview.

Keys: r re-render · h/l previous/next · o open the PNG · x ask Claude to review the layout

Switch tabs with 1 2 3.

Troubleshooting

• The band says Xcode MCP server "xcode" not connected. Run /mcp and check that the xcode server is connected. Check that xcrun mcp-server status reports it as enabled.
• Every action asks for permission. Add the mcp__xcode allow rule from Setup.
• The first preview takes a minute or more. Xcode builds the preview host on the first render. Later renders are fast.
• The preview always renders on the same simulator. Xcode picks the preview device itself, and the MCP server doesn't let you choose it yet.
• No image in the Canvas pane. Your terminal doesn't support the kitty graphics protocol. The pane shows the PNG path instead; press o to open it.

Development

mods/xcode-mods/hooks/register.tsx   # entry: wires both modules
mods/xcode-mods/hooks/build.tsx      # toolbar band + Build · Run · Tests pane
mods/xcode-mods/hooks/canvas.tsx     # SwiftUI preview pane
Sandbox/                             # test iOS app (XcodeGen: project.yml)
.mcp.json                            # xcode MCP server for this repo

To run the plugin from source with hot reload:

claude --plugin-dir mods/xcode-mods

Claude Code writes the mod API types into mods/xcode-mods/.claude-plugin/types/ (git-ignored) when it loads the plugin with --plugin-dir, so start a session that way once before type-checking with tsc -p mods/xcode-mods.

To check and test the plugin:

claude plugin validate mods/xcode-mods
claude plugin test mods/xcode-mods

Sandbox is a SwiftUI counter app with Swift Testing tests. Playground.swift holds an intentional warning; edit it to break the build. After editing project.yml, regenerate the project with cd Sandbox && xcodegen.

Author

Artem Novichkov, https://artemnovichkov.com/

License

The project is available under the MIT license. See the LICENSE file for more info.