A native macOS command-line tool that augments the Xcode development workflow with advanced, stateful functionality.

! This project is WIP - not yet production-ready.

This project was greatly inspired by XcodeBuildMCP and serves as an experiment to explore whether Model Context Protocol (MCP) servers are necessary for Xcode automation, or if traditional CLI tools provide a better solution.

The goal of xcsentinel is to test the hypothesis that well-designed command-line tools can be more effective than MCP servers for developer tooling:

• Direct Integration: CLI tools integrate naturally with existing developer workflows, scripts, and CI/CD pipelines
• Simplicity: No additional protocol layer or server management required
• Performance: Direct execution without the overhead of client-server communication
• Composability: Unix philosophy - tools that do one thing well and compose together
• AI-Friendly: Structured output (JSON) makes it easy for AI agents to parse and use

While MCP servers have their place for certain integrations, this project demonstrates that for build automation and development workflows, a thoughtfully designed CLI tool can provide a superior developer experience.

• Accelerated Builds: Intelligent incremental build system leveraging xcodemake for fast, efficient builds
• Workflow Automation: Unified run command to build, install, and launch applications
• Stateful Log Management: Session-based management for background log streams with automatic cleanup
• JSON Output Support: Machine-readable output for automation and AI agents
• Smart Device Handling: Automatic resolution of simulators and devices with clear error messages

git clone https://github.com/steipete/xcsentinel.git
cd xcsentinel
swift build -c release
sudo cp .build/release/xcsentinel /usr/local/bin/

brew tap steipete/xcsentinel
brew install xcsentinel

• macOS 14.0+
• Xcode Command Line Tools
• Swift 5.9+
• Optional: xcodemake for incremental builds

Build with automatic incremental build detection:

xcsentinel build --scheme MyApp --destination "platform=iOS Simulator,name=iPhone 15"

Build with workspace:

xcsentinel build --scheme MyApp --workspace MyApp.xcworkspace --destination "platform=iOS Simulator,name=iPhone 15"

Disable incremental builds:

xcsentinel build --scheme MyApp --project MyApp.xcodeproj --destination "id=ABC123" --no-incremental

Build, install, and launch in one command:

xcsentinel run --scheme MyApp --destination "platform=iOS Simulator,name=iPhone 15 Pro"

With JSON output for automation:

xcsentinel run --scheme MyApp --destination "id=ABC123" --json

Start a log session:

xcsentinel log start --udid ABC123 --bundle-id com.example.MyApp
# Output: Started log session: session-1

View logs from a session:

# Last 100 lines (default)
xcsentinel log stop session-1

# Full log output
xcsentinel log stop session-1 --full

Stream live logs:

xcsentinel log tail session-1

List active sessions:

xcsentinel log list
# Output:
# Active log sessions:
#   session-1 - PID: 50123, Bundle: com.example.MyApp, Target: ABC123

Clean up stale sessions:

xcsentinel log clean

1. xcsentinel checks for a .xcsentinel.rc marker file
2. Compares modification times against all project files
3. If valid, uses existing Makefile or generates one with xcodemake
4. Falls back to standard xcodebuild if needed
5. Automatically cleans up on build failures

• Logs are stored in ~/.xcsentinel/logs/
• Session state is tracked in ~/.xcsentinel/state.json
• Automatic cleanup of terminated processes
• Supports both simulators (via simctl) and devices (via devicectl)

xcsentinel provides clear error messages for common issues:

• Ambiguous simulator names with suggestions
• Missing workspace/project specifications
• Build failures with detailed output
• Session not found errors

All commands support --json flag for machine-readable output:

{
  "success": true,
  "app_path": "/path/to/MyApp.app",
  "bundle_id": "com.example.MyApp",
  "target_udid": "ABC123"
}

Error responses:

{
  "success": false,
  "error": {
    "code": "SIMULATOR_NOT_FOUND",
    "message": "Simulator with name 'iPhone 99' not found."
  }
}

After experimenting with both approaches, here's what we learned:

1. Lower Barrier to Entry: Developers already understand CLI tools. No need to learn MCP protocols or set up servers.

2. Better Debugging: When something goes wrong, it's much easier to debug a CLI tool than a client-server protocol.

3. Ecosystem Integration: Works seamlessly with Make, shell scripts, GitHub Actions, and other existing tools.

4. Stateful When Needed: The log session management demonstrates that CLI tools can maintain state effectively without requiring a persistent server.

5. AI Integration: The JSON output mode provides the same structured data that MCP would, but through a simpler interface that AI agents can easily invoke.

Special thanks to Cameron Cooke for creating XcodeBuildMCP, which inspired this exploration into the best way to provide Xcode automation tools for both human developers and AI agents.

Contributions are welcome! Please read:

• Software Design Document - Original specification
• Spec Compliance - Implementation compliance and known limitations
• Testing Guide - How to write and run tests

MIT License - see LICENSE file for details.