xbridge

name: xbridge description: "Use when working with Xcode projects — building, testing, reading files, searching code, or running SwiftUI previews. Triggers include: 'build Xcode project', 'run tests', 'xbridge', 'Xcode MCP', or any Xcode development task."

xbridge Skill

This skill enables AI agents to interact with Xcode projects via the xbridge CLI.

Xcode must be running. xbridge communicates with Xcode directly — if Xcode is not open with a project loaded, every command will fail. Before proceeding, confirm Xcode is running and a project is open. If it's not, open it:

open -a Xcode          # opens Xcode without a project
open MyApp.xcodeproj   # opens a specific project
open MyApp.xcworkspace # opens a workspace

Sometimes the Xcode app is not called Xcode.app, but rather a versioned name like Xcode-26.0.app. List all Xcode apps with:

ls /Applications/Xcode*.app

If the bridge shows as unhealthy, ensure Xcode is open with a project and MCP is enabled in Xcode > Settings > Intelligence.

Setup

Run:

which xbridge

If found, verify the bridge is running:

xbridge status

If the output indicates the bridge is not running, tell the user:

The Xcode MCP bridge isn't running. Open Xcode with your project first:

open MyApp.xcodeproj   # or .xcworkspace

Then check status again — the daemon auto-recovers the bridge once Xcode is running:

xbridge status

If the bridge shows as awaiting-permission, tell the user: "Xcode is asking for permission — click Allow in the dialog." Wait for confirmation before continuing.

Wait for the user to confirm before continuing.

If found and bridge is running, skip to Using xbridge.

If not found, install it:

brew tap 4rays/tap
brew install xbridge

Confirm the install:

xbridge status

Enable Xcode MCP: open Xcode > Settings (⌘,) → Intelligence → enable Xcode Tools under Model Context Protocol.

Then open your project in Xcode and proceed to Using xbridge.

Using xbridge

Prerequisites

• xbridge installed (brew install xbridge via the 4rays/tap tap)
• Xcode running with a project open
• Xcode MCP enabled in Xcode > Settings > Intelligence > Model Context Protocol

Get a Tab ID First

Most commands require a tab ID. Always start with:

xbridge list-windows

This returns identifiers like windowtab1, windowtab2. Use the relevant one in subsequent commands.

Timeouts

Build, test, and log commands can run for minutes on large projects. Always pass --timeout when calling these via xbridge call, or set a generous shell timeout. Start conservative and scale up:

Commands most likely to need a timeout: build, test, test-run, build-log, refresh-issues.

Commands Reference

Daemon & Status

Discovery

File Operations

Build & Test

Advanced

Common Workflows

Build a project

xbridge list-windows
# → windowtab1  /path/to/Project.xcodeproj

xbridge build windowtab1
xbridge build-log windowtab1

Run tests

xbridge list-windows
xbridge test-list windowtab1
# Output truncates on large projects — full list written to path in `fullTestListPath` field
xbridge test windowtab1
# or a specific test — parentheses () required in identifier or test won't be found:
xbridge test-run windowtab1 MyTarget 'MyTests/testSomething()'

Edit a file

xbridge update windowtab1 Sources/MyView.swift 'Text("Hello")' 'Text("Hello, World!")'

Search code

xbridge grep "someFunction" windowtab1 Sources/

Get Xcode issues

xbridge list-windows
# → windowtab1  /path/to/Project.xcodeproj

xbridge issues windowtab1
# Lists errors only (default)

xbridge issues windowtab1 warning
# Lists warnings and above

xbridge issues windowtab1 remark
# Lists everything

# Refresh diagnostics for a specific file first if issues are stale.
# Path is relative to workspace root (ProjectName/Path/To/File.swift):
xbridge refresh-issues windowtab1 MyApp/Sources/MyView.swift
xbridge issues windowtab1

Search documentation

xbridge docs "SwiftUI List" SwiftUI

Note: docs output can be large (30KB+). Use narrow, specific queries and pass a framework name to limit results.

Troubleshooting

xbridge not found Install with brew tap 4rays/tap && brew install xbridge.

xbridge status shows bridge down or unhealthy Ensure Xcode is open with a project and MCP is enabled in Xcode > Settings > Intelligence > Model Context Protocol. The daemon auto-starts and retries on the next command.

Command returns WAITING_FOR_PERMISSION Tell the user: "Xcode is asking for permission — click Allow in the dialog." Wait for confirmation, then re-run the same command. The daemon will retry automatically once permission is granted.

No tab IDs from xbridge list-windows Xcode must be running with a project open. Run open MyApp.xcodeproj first.

Xcode MCP not enabled Go to Xcode > Settings > Intelligence > Model Context Protocol and enable Xcode Tools.

MCP permission denied In Xcode Settings, revoke the process entry under MCP. The next tool command will trigger a fresh permission dialog — tell the user to click Allow.

Project Context

Add an AGENTS.md or CLAUDE.md in your project root:

# Project Context

## Build System

- iOS 18 SwiftUI project
- Main scheme: MyApp

## Testing

- Test scheme: MyAppTests

## Project Structure

- Sources in: Sources/
- Tests in: Tests/

Resources

• Apple MCP Documentation