XBridge — Build, Test, and Run Xcode Projects in VS Code

Stay in VS Code for the everyday Xcode workflow.
Build, test, and run iOS and macOS apps with simulator and physical-device control, native Test Explorer integration, inline diagnostics, and eight AI agent tools.

Installation • Features • AI Tools • Physical Devices • Shortcuts • Contributing • Settings

Installation

Install XBridge from the Visual Studio Marketplace, or open the Extensions view in VS Code and search for chaiwithcode.xbridge.

Why XBridge?

Run the core Xcode workflow from the editor where you write Swift.
Target simulators or connected iPhones and iPads through Apple's native tools.
See compiler and test failures inline and in VS Code's Problems and Test Explorer views.
Let compatible AI coding agents build, test, run, clean, and inspect diagnostics through dedicated tools.
Keep Xcode one click away for Interface Builder, Instruments, signing, and project settings.

Features

1. Build, Run & Test

Xcode-Style Status Bar Toolbar: Persistent controls right where you expect them:
- Run / Stop toggle button (⌃⌘R / ⌃⌘.)
- Build button (⌃⌘B)
- Test button (⌃⌘U)
- Clickable Scheme selector
- Clickable Destination selector (Simulators & Physical Devices)
- Live Activity Pill: Displays active compilation phase (Building → Linking → Testing → Launching) with error/warning counts on completion.
- App Running Pill: Green status indicator when your app is active; click anytime to terminate it.

2. Physical iOS Device Support (`devicectl`)

Seamlessly deploy and run your apps on real iPhones and iPads running iOS 17+.
Uses Apple's modern CoreDevice framework (xcrun devicectl) without needing third-party Python daemons or jailbreaks.
Automatic device discovery: connected USB and paired Wi-Fi devices automatically appear in the Destinations sidebar.
Verifies Developer Mode status before building, providing actionable warnings if disabled.

3. Simulator Management Superpowers

Right-click any simulator in the Destinations panel to access deep device utilities:

📸 Take Screenshot: Captures clean PNG screenshots directly to your workspace.
🎬 Record Screen: One-click screen recording saved as H.264 video.
🌙 Toggle Appearance: Instantly switch between Light and Dark mode.
🔗 Open URL / Deep Link: Test your app's custom URL schemes and universal links.
📂 Open App Container: Open your app's Documents/Library sandbox folder in Finder.
🗑️ Uninstall App: Remove installed builds with a single click.
📋 Copy UDID: Fast clipboard access for scripting or provisioning.
🧼 Erase Simulator: Reset simulator contents and settings to factory state.

4. Modern Testing with XCTest & Swift Testing (`@Test`)

Native integration with the VS Code Test Explorer.
Discovers and runs both traditional XCTest suites and modern Swift Testing (@Test, @Suite) tests.
Gutter play buttons (▶️) next to test functions for single-test execution.
Accurately captures assertion failures with file, line, and expression decomposition.

5. Inline Diagnostics & Searchable Issue Viewer

Compiler errors, warnings, and test failures are mapped directly into the VS Code Problems panel and highlighted with inline squiggly lines.
Click the status-bar result pill anytime to open a fuzzy-searchable QuickPick of all build issues and jump straight to the source line.

6. Dependency Management & Xcode Integration

Resolve Package Dependencies (⌃⌘P): Run xcodebuild -resolvePackageDependencies without touching terminal.
Open in Xcode: Quickly open the active project or workspace in Xcode.app whenever you need Interface Builder or Instruments.

AI Agent Tools (GitHub Copilot)

XBridge exposes 8 dedicated Language Model Tools directly to AI coding agents (such as GitHub Copilot in VS Code or Cursor). Reference them with # in prompt:

Tool Reference	Tool Name	Description
`#iosBuild`	`xbridge_build`	Compiles the active scheme and returns structured compiler errors and warnings.
`#iosTest`	`xbridge_test`	Runs test suites (or an individual test) and reports test failures with file/line locations.
`#iosRun`	`xbridge_run`	Builds, installs, and launches the app on the selected simulator or physical device.
`#iosDiagnostics`	`xbridge_readDiagnostics`	Reads compiler errors and test failures from the last run without rebuilding.
`#iosClean`	`xbridge_clean`	Cleans the Xcode build folder (`DerivedData`) for a fresh compilation.
`#iosSchemes`	`xbridge_listSchemes`	Discovers available schemes, configurations, and build targets.
`#iosSimulators`	`xbridge_listSimulators`	Lists all installed simulators and their status (Booted/Shutdown).
`#iosBoot`	`xbridge_bootSimulator`	Boots a specified simulator by UDID and opens Simulator.app.

AI Pair Programming Example: "Use #iosBuild to compile the app. If there are any compiler errors, use #iosDiagnostics to inspect the error lines, fix the Swift code, and re-run #iosBuild until it succeeds."

Requirements

macOS with Xcode and command-line developer tools installed (xcodebuild, xcrun simctl).
Physical device support requires Xcode 15+ (xcrun devicectl).
For physical device builds, code signing (Development Team & Signing Identity) must be configured in your Xcode project.

Getting Started

Open a workspace folder containing an .xcodeproj, .xcworkspace, or Package.swift.
Click the XBridge icon in the Activity Bar.
Select your desired Scheme and Destination (Simulator or Connected Physical Device).
Press ⌃⌘B to build, or ⌃⌘R to build and launch!

Run XBridge: Getting Started from the Command Palette (⇧⌘P) anytime for a guided walkthrough.

Keyboard Shortcuts

Command	macOS Shortcut	Description
XBridge: Build	⌃⌘B	Build the current scheme
XBridge: Build & Run	⌃⌘R	Build and launch on simulator or device
XBridge: Run Tests	⌃⌘U	Run test plan or target
XBridge: Clean Build Folder	⌃⌘K	Clean DerivedData build products
XBridge: Stop	⌃⌘.	Cancel active build or terminate running app
XBridge: Select Destination	⌃⌘D	Switch destination device or simulator
XBridge: Resolve Package Dependencies	⌃⌘P	Resolve SPM package dependencies

Settings

Configure XBridge in your User or Workspace settings.json:

Setting	Type	Default	Description
`xbridge.projectPath`	`string`	`""`	Path to `.xcodeproj`, `.xcworkspace`, or `Package.swift` (auto-detected if empty).
`xbridge.scheme`	`string`	`""`	Xcode scheme to build.
`xbridge.configuration`	`string`	`"Debug"`	Build configuration (`Debug` or `Release`).
`xbridge.destination`	`string`	`""`	UDID of the selected target simulator or physical device.
`xbridge.testPlan`	`string`	`""`	`.xctestplan` to run, overriding scheme default.
`xbridge.testTarget`	`string`	`""`	Specific test target to run (or all tests if empty).
`xbridge.derivedDataPath`	`string`	`""`	Custom DerivedData directory. Defaults to `.build/DerivedData`.
`xbridge.extraBuildArgs`	`array`	`[]`	Extra arguments injected into `xcodebuild` invocations.
`xbridge.streamAppLogs`	`boolean`	`true`	Stream app `stdout`/`stderr` into the "XBridge App" output channel.
`xbridge.openSimulatorOnRun`	`boolean`	`true`	Focus Simulator.app when launching on a simulator.
`xbridge.autoRevealBuildLog`	`boolean`	`false`	Automatically show the build output channel when an action starts.

Contributing

We welcome community contributions! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

Fork the repository: https://github.com/chaiwithcode/Xbridge
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

XBridge

chaiwithcode