# Xclaude Plugin

> iOS development ClaudeCode plugin for mindful token and context usage. Contains modular MCPs that group various Xcode/IDB tools based on your current workflow.

- **Type:** MCP server
- **Install:** `agentstack add mcp-conorluddy-xclaude-plugin`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [conorluddy](https://agentstack.voostack.com/s/conorluddy)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [conorluddy](https://github.com/conorluddy)
- **Source:** https://github.com/conorluddy/xclaude-plugin

## Install

```sh
agentstack add mcp-conorluddy-xclaude-plugin
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# xClaude Plugin

```
/plugin marketplace add conorluddy/xclaude-plugin
```

**Modular iOS development automation for Claude Code**

Build, test, and automate iOS apps through natural conversation with Claude. 8 workflow-specific MCP servers with 24 tools across Xcode, Simulator, and IDB.

**Enable only what you need.** Each MCP is purpose-built for specific workflows, keeping your context window lean. Plus, our tools intelligently encapsulate Xcode output (errors, test results, build logs) so Claude processes structured JSON instead of raw 50+ line logs—saving significant tokens and enabling faster feedback loops.

## Features

### 🎯 Modular Architecture

- **8 workflow-specific MCP servers** (600-3500 tokens each)
- **Enable only what you need** - Ultra-minimal to full-featured
- **23 shared tools** across Xcode, Simulator, and IDB
- **Single source of truth** - tools defined once, imported by MCPs

### 🔥 Surgical MCPs (Ultra-Focused)

- **xc-build** (~600 tokens) - Build validation, errors, clean, list schemes
- **xc-launch** (~400 tokens) - Simulator app lifecycle: install and launch
- **xc-interact** (~900 tokens) - Pure UI interaction, no build

### 📦 Core Workflow MCPs

- **xc-ai-assist** (~1400 tokens) - Build + UI automation + screenshots
- **xc-setup** (~800 tokens) - Environment configuration and validation
- **xc-testing** (~1200 tokens) - Test execution + UI flows
- **xc-meta** (~700 tokens) - Project maintenance and housekeeping

### 🚀 Full Access

- **xc-all** (~3500 tokens) - All 24 tools for complex workflows

### 📚 8 Procedural Skills (Loaded On-Demand)

- **xcode-workflows** - Build system guidance and result analysis
- **simulator-workflows** - Device and app lifecycle patterns
- **ui-automation-workflows** - Accessibility-first automation
- **accessibility-testing** - WCAG compliance and quality checks
- **ios-testing-patterns** - Test execution and flaky test detection
- **crash-debugging** - Crash log analysis and symbolication
- **performance-profiling** - Instruments integration
- **state-management** - Cache and configuration management

## Installation

### From GitHub (Recommended)

```bash
/plugin marketplace add conorluddy/xclaude-plugin
/plugin install xclaude-plugin
```

### From Local Development

```bash
/plugin marketplace add /path/to/xclaude-plugin
/plugin install xclaude-plugin
```

## First 60 Seconds

Just installed? Enable **xc-build** and **xc-launch** for rapid development:

```
1. In Claude settings, enable "xc-build" and "xc-launch" MCPs
2. Ask Claude: "Build and run MyApp on iPhone 15"
3. Done! ✨
```

That's it. **xc-build** + **xc-launch** gives you a composable development loop: build with xc-build, then install & launch with xc-launch. Claude orchestrates the two-step workflow. If you need other workflows (testing, setup, UI automation), see **Choosing the Right MCP** below.

## Requirements

- macOS 13.0+ or Linux
- Xcode 15.0+ (macOS only, for iOS development)
- Node.js 18+
- Optional: IDB (Facebook iOS Development Bridge) for advanced UI automation

## Migration Guide (v0.4.0)

If you're upgrading from an earlier version, note these breaking changes:

### Renamed Server: `xc-build-and-launch` → `xc-launch`

**What changed:**
- Server renamed from **xc-build-and-launch** to **xc-launch** for clarity
- **Removed:** `xcode_build_and_launch` monolithic tool (with `skip_build` flag), plus `xcode_build`, `xcode_clean`, `xcode_list` (moved to xc-build)
- **Now contains:** Only `simulator_install_app` and `simulator_launch_app`
- **Philosophy:** Use **xc-build** + **xc-launch** together for development loop

**Why:** The monolithic `xcode_build_and_launch` tool coupled build, install, and launch into a single operation. The new architecture separates build concerns (xc-build) from simulator lifecycle (xc-launch), enabling:
- Better error recovery (retry individual steps)
- Clearer mental model (build → install → launch)
- No `skip_build` code smell
- Follows Single Responsibility Principle

**Action required:**
1. Update your `.mcp.json` configuration:
   ```diff
   - "xc-build-and-launch": {
   -   "command": "node",
   -   "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-servers/xc-build-and-launch/dist/index.js"]
   + "xc-launch": {
   +   "command": "node",
   +   "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-servers/xc-launch/dist/index.js"]
   ```
2. In Claude settings, enable "xc-launch" instead of "xc-build-and-launch"

**Previous versions:**
- `v0.3.0`: `xc-run` → `xc-build-and-launch`
- `v0.3.0`: `xc-compile` → `xc-build`, `xc-hybrid` → `xc-all`

See `.mcp.json.example` for the current configuration.

## Choosing the Right MCP

### Enable the Right MCP for Your Task

**IMPORTANT**: Enable **ONE MCP at a time** for optimal token efficiency. Choose based on your current workflow:

```
☐ xc-build                # Build validation, errors, clean? (~600 tokens)
☐ xc-launch               # Simulator lifecycle: install + launch? (~400 tokens)
☐ xc-interact             # Testing UI with app already built? (~900 tokens)
☐ xc-ai-assist            # AI-driven UI iteration? (~1400 tokens)
☐ xc-setup                # First time setup? (~800 tokens)
☐ xc-testing              # Running test suites? (~1200 tokens)
☐ xc-meta                 # Maintenance tasks? (~700 tokens)
☐ xc-all                  # Complex workflow needing everything? (~3500 tokens)

💡 Tip: Enable xc-build + xc-launch together for development loop (~1000 tokens total)
```

### Example Workflows

**Scenario 1: Build and fix errors**

```
Enable: xc-build (~600 tokens)

"Build the project and show me the errors"

→ Uses xcode_build with automatic error extraction
→ Returns up to 10 errors for quick fixes
→ 87% less tokens than old architecture!
```

**Scenario 2: Rapid development - build and run**

```
Enable: xc-build + xc-launch (~1000 tokens)

"Build and run MyApp on iPhone 15"

→ Claude orchestrates: build (xc-build) → install & launch (xc-launch)
→ Composable two-server workflow
→ Better error recovery (retry individual steps)
→ Perfect for iterative development
```

**Scenario 3: Testing UI flows (app already built)**

```
Enable: xc-interact (~900 tokens)

"Tap the Login button, then check if the profile screen appears"

→ Queries accessibility tree (3-4x faster than screenshots)
→ Taps elements by coordinates
→ Validates UI state without rebuilding
```

**Scenario 4: AI-driven UI iteration**

```
Enable: xc-ai-assist (~1400 tokens)

"Update the button color to blue, rebuild, and show me a screenshot"

→ Modifies code, builds, captures screenshot
→ Complete workflow in one MCP
→ Includes visual feedback (screenshots)
```

## Architecture

### Modular MCP Design

```
┌─────────────────────────────────────────────────────┐
│  Shared Tool Library (24 tools)                     │
│  ├─ Xcode (6): build, build+run, clean, test, list, version │
│  ├─ Simulator (12): boot, install, screenshot, etc.│
│  └─ IDB (6): describe, tap, input, gesture, etc.   │
└─────────────────────────────────────────────────────┘
         ↓ Tools imported by MCP servers ↓
┌─────────────────────────────────────────────────────┐
│  8 Workflow-Specific MCP Servers                    │
│  ├─ xc-build:            3 tools   (~600 tokens)   │
│  ├─ xc-launch:           2 tools   (~400 tokens)   │
│  ├─ xc-interact:         6 tools   (~900 tokens)   │
│  ├─ xc-ai-assist:        7 tools   (~1400 tokens)  │
│  ├─ xc-setup:            5 tools   (~800 tokens)   │
│  ├─ xc-testing:          6 tools   (~1200 tokens)  │
│  ├─ xc-meta:             6 tools   (~700 tokens)   │
│  └─ xc-all:              24 tools  (~3500 tokens)  │
└─────────────────────────────────────────────────────┘
```

### Key Benefits

**For Users:**

- Enable only what you need (300-3500 tokens)
- Clear mental model (workflow-based naming)
- No tool duplication confusion
- Easy to toggle on/off in Claude settings

**For Developers:**

- Single source of truth (shared tools)
- Easy testing (isolated functions)
- Simple maintenance (update once)
- Type-safe throughout (zero `any` usage)

## MCP Server Reference

### 🔥 Surgical MCPs

| MCP             | Tools | Token Cost | Use When                                               |
| ---------------------- | ----- | ---------- | ------------------------------------------------------ |
| **xc-build**           | 3     | ~600       | Build validation with clean/scheme discovery            |
| **xc-launch**          | 2     | ~400       | Simulator lifecycle: install and launch app            |
| **xc-interact**        | 6     | ~900       | Testing UI flows with app already built                |

### 📦 Core Workflow MCPs

| MCP              | Tools | Token Cost | Use When                                      |
| ---------------- | ----- | ---------- | --------------------------------------------- |
| **xc-ai-assist** | 7     | ~1400      | AI UI iteration with visual feedback          |
| **xc-setup**     | 5     | ~800       | Initial setup, environment validation         |
| **xc-testing**   | 6     | ~1200      | Running test suites + UI automation           |
| **xc-meta**      | 6     | ~700       | Maintenance, housekeeping, environment checks |

### 🚀 Full Access

| MCP       | Tools | Token Cost | Use When                             |
| --------- | ----- | ---------- | ------------------------------------ |
| **xc-all** | 23    | ~3500      | Complex workflows needing everything |

**Pro tip**: Don't enable multiple MCPs simultaneously - tool duplication will increase token usage! Use xc-all instead for multi-workflow sessions.

## Cheat Sheet - Which Tools Are in Which MCP?

Quick reference to find which MCP has the tools you need:

### Xcode Tools

| Tool | xc-build | xc-launch | xc-interact | xc-ai-assist | xc-setup | xc-testing | xc-meta | xc-all |
|------|:--------:|:---------:|:-----------:|:------------:|:--------:|:----------:|:-------:|:------:|
| `xcode_build` | ✅ | | | ✅ | | | | ✅ |
| `xcode_build_and_launch` | | | | | | | | ✅ |
| `xcode_clean` | ✅ | | | | | | ✅ | ✅ |
| `xcode_test` | | | | | | ✅ | | ✅ |
| `xcode_list` | ✅ | | | | | | ✅ | ✅ |
| `xcode_version` | | | | | ✅ | | ✅ | ✅ |

### Simulator Tools

| Tool | xc-build | xc-launch | xc-interact | xc-ai-assist | xc-setup | xc-testing | xc-meta | xc-all |
|------|:--------:|:---------:|:-----------:|:------------:|:--------:|:----------:|:-------:|:------:|
| `simulator_list` | | | | | ✅ | | | ✅ |
| `simulator_boot` | | | | | ✅ | | | ✅ |
| `simulator_shutdown` | | | | | | | ✅ | ✅ |
| `simulator_create` | | | | | ✅ | | | ✅ |
| `simulator_delete` | | | | | | | ✅ | ✅ |
| `simulator_install_app` | | ✅ | | | | | | ✅ |
| `simulator_launch_app` | | ✅ | | | | | | ✅ |
| `simulator_terminate_app` | | | | | | | | ✅ |
| `simulator_screenshot` | | | | ✅ | | ✅ | | ✅ |
| `simulator_openurl` | | | | | | | | ✅ |
| `simulator_get_app_container` | | | | | | | | ✅ |
| `simulator_health_check` | | | | | ✅ | | ✅ | ✅ |

### IDB Tools

| Tool | xc-build | xc-launch | xc-interact | xc-ai-assist | xc-setup | xc-testing | xc-meta | xc-all |
|------|:--------:|:---------:|:-----------:|:------------:|:--------:|:----------:|:-------:|:------:|
| `idb_describe` | | | ✅ | ✅ | | ✅ | | ✅ |
| `idb_tap` | | | ✅ | ✅ | | ✅ | | ✅ |
| `idb_input` | | | ✅ | ✅ | | ✅ | | ✅ |
| `idb_gesture` | | | ✅ | | | ✅ | | ✅ |
| `idb_find_element` | | | ✅ | ✅ | | | | ✅ |
| `idb_check_quality` | | | ✅ | ✅ | | | | ✅ |

## Tool Library (24 Total)

### Xcode Tools (6)

- `xcode_build` - Build with automatic error extraction
- `xcode_build_and_launch` - Build, install, and launch on simulator
- `xcode_clean` - Clean build artifacts
- `xcode_test` - Run XCTest suites
- `xcode_list` - List schemes/targets
- `xcode_version` - Check Xcode installation

### Simulator Tools (12)

- `simulator_list` - Enumerate simulators
- `simulator_boot` - Boot device
- `simulator_shutdown` - Shutdown device
- `simulator_create` - Create new simulator
- `simulator_delete` - Delete simulator
- `simulator_install_app` - Install app
- `simulator_launch_app` - Launch app
- `simulator_terminate_app` - Terminate app
- `simulator_screenshot` - Capture screenshot
- `simulator_openurl` - Open URL/deep link
- `simulator_get_app_container` - Get app container path
- `simulator_health_check` - Validate environment

### IDB Tools (6)

- `idb_describe` - Query accessibility tree (accessibility-first!)
- `idb_tap` - Tap coordinates
- `idb_input` - Type text or press keys
- `idb_gesture` - Swipes and hardware buttons
- `idb_find_element` - Search by label (semantic)
- `idb_check_quality` - Assess accessibility data richness

## Configuring Your Project

Add this section to your project's `.claude/CLAUDE.md` file. This guides Claude on when and why to use the xclaude-plugin tools instead of directly calling Xcode or shell commands:

```markdown
## xclaude-plugin: Why and When to Use These Tools

The xclaude-plugin provides 8 modular MCPs with 24 specialized iOS tools. **Always prefer these over raw `xcodebuild` or shell commands** for iOS development tasks. Here's why:

### Why These Tools Trump Raw Commands

| Task                 | Direct Bash                                                    | xclaude-plugin                   | Why Plugin Wins                                                           |
| -------------------- | -------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------- |
| Build + get errors   | `xcodebuild -scheme Foo 2>&1` (50+ lines of parsing)           | `xcode_build` tool               | Auto-extracts up to 10 errors, structured JSON, 87% fewer tokens          |
| Test suite execution | `xcodebuild test` + manual parsing                             | `xcode_test` tool                | Parses results, reports failures, timing, code coverage                   |
| Simulator screenshot | `xcrun simctl io booted screenshot /tmp/x.png` + file handling | `simulator_screenshot` tool      | Auto-saves, encoded output, accessible in response                        |
| UI automation        | Manual coordinate finding + shell taps                         | `idb_describe` + `idb_tap` tools | Queries accessibility tree (120ms), semantic element finding, 3-4x faster |
| App installation     | `xcrun simctl install booted App.app`                          | `simulator_install_app` tool     | Builds, finds app, installs, validates—one command                        |

### When to Use Each MCP

**Use `xc-build`** (~600 tokens) when:

- Building and fixing errors
- Need to clean build artifacts
- Discovering schemes/targets in project
- Build validation and configuration

**Use `xc-launch`** (~400 tokens) when:

- Installing and launching an app on the simulator

**Use `xc-interact`** (~900 tokens) when:

- Testing UI flows with app already built
- Automating screen validation without code changes
- Need accessibility-first element querying

**Use `xc-ai-assist`** (~1400 tokens) when:

- Iterating on UI with live feedback (code change → screenshot)
- Need visual validation of changes
- Combining code modification with testing

**Use `xc-testing`** (~1200 tokens) when:

- Running test suites and analyzing results
- Need both unit tests and UI automation
- Debugging test failures

**Use `xc-setup`** (~800 tokens) when:

- First-time environment validation
- Checking Xcode/simulator health
- Discovering project structure (schemes, targets)

**Use `xc-meta`** (~700 tokens) when:

- Maintenance tasks (clearing derived data, managing simulators)
- Non-coding iOS project operations
- Environment housekeeping

**Use `xc-all`** (~3500 tokens) when:

- Complex workflows requiring multiple tool categories
- Don't know which single MCP fits the task
- Need flexibility to pivot between workflows

### Critical: Prefer Plugin Tools Over Bash

When you encounter a task that could use either approach, **always choose the plugin tool**.

**Do

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [conorluddy](https://github.com/conorluddy)
- **Source:** [conorluddy/xclaude-plugin](https://github.com/conorluddy/xclaude-plugin)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-conorluddy-xclaude-plugin
- Seller: https://agentstack.voostack.com/s/conorluddy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.