Simple, reliable bash wrappers for Xcode builds and iOS/visionOS app debugging with Claude Code.

A lightweight alternative to heavy MCP servers—just bash scripts that wrap Apple's tools and capture output to files.

• ✅ Dead Simple: 3 bash scripts, ~100 lines total
• ✅ Reliable: Wraps Apple's battle-tested xcodebuild and simctl
• ✅ Token-Efficient: File-based outputs, grep what you need
• ✅ No Dependencies: Uses standard macOS tools (xcrun, simctl)
• ✅ Works with Claude Code: Perfect for AI-assisted development
• ✅ Portable: Copy installer to any Xcode project
• ✅ Timestamped Outputs: Each build and log capture gets its own file

• INSTALL-XCODE-SCRIPTS.md - Installation guide
• INSTALLER-USAGE.md - Advanced usage patterns
• .claude/building-with-xcode.md - Complete reference (installed by installer)

bash install-xcode-scripts.sh

./claude/scripts/xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  build \
  -destination 'generic/platform=visionOS Simulator'

# Start capture
./claude/scripts/capture-logs com.yourapp.vision

# Launch your app in Xcode (Cmd+R)
# Do your testing...

# Stop capture
./claude/scripts/stop-logs

# Search results
grep ERROR ./build/logs/logs-*.txt

grep -i error ./build/xcodebuild/build-*.txt
grep -i crash ./build/logs/logs-*.txt

This project replaces heavyweight MCP servers with focused, reliable bash wrappers:

• File-based: Outputs saved to timestamped files, not in-memory responses
• Searchable: Use grep/head/tail to find what you need
• Simple: No TypeScript, no protocols, no complexity
• Token-Efficient: Only load the data you need
• Stable: Built on Apple's tools, no maintenance required

See INSTALL-XCODE-SCRIPTS.md for:

• Installation instructions
• What gets installed
• Quick start examples
• Troubleshooting

See INSTALLER-USAGE.md for:

• Advanced usage patterns
• Team distribution
• CI/CD integration
• FAQ

After installation, read the complete guide:

cat ./.claude/building-with-xcode.md

./claude/scripts/xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  build \
  -destination 'generic/platform=visionOS Simulator'

./claude/scripts/xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  build \
  -destination generic/platform=visionOS

./claude/scripts/xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  test \
  -destination 'generic/platform=visionOS Simulator'

# Capture logs from your app's subsystem
./claude/scripts/capture-logs com.yourcompany.myapp

# Capture from a specific subsystem
./claude/scripts/capture-logs com.yourcompany.myapp.CoreData

# Capture from a specific simulator
./claude/scripts/capture-logs com.yourapp booted

# Find all errors
grep -i error ./build/xcodebuild/build-*.txt

# Find warnings
grep -i warning ./build/xcodebuild/build-*.txt

# Show context (3 lines before/after)
grep -C 3 "error:" ./build/xcodebuild/build-*.txt

# Count occurrences
grep -c "ViewController" ./build/xcodebuild/build-*.txt

# Find crashes
grep -i crash ./build/logs/logs-*.txt

# Find specific class logs
grep "MyViewController" ./build/logs/logs-*.txt

# Find with context
grep -C 5 "ERROR" ./build/logs/logs-*.txt

# Real-time search multiple log files
tail -f ./build/logs/logs-*.txt | grep MyPattern

xcode-cli-tools/
├── install-xcode-scripts.sh          ← Run this
├── INSTALL-XCODE-SCRIPTS.md          ← Read this first
├── INSTALLER-USAGE.md                ← Advanced usage
├── README.md                         ← You are here
│
After running installer:
├── .claude/
│   ├── scripts/
│   │   ├── capture-logs
│   │   ├── stop-logs
│   │   └── xcodebuild
│   └── building-with-xcode.md
│
└── build/
    ├── logs/           ← App console logs
    └── xcodebuild/     ← Build outputs

These scripts are optimized for Claude Code integration:

User: "Build the visionOS app"
↓
Claude runs: ./claude/scripts/xcodebuild -workspace MyApp.xcworkspace -scheme MyApp build
↓
Output saved to: ./build/xcodebuild/build-20251021-143022.txt
↓
User: "Find errors"
↓
Claude runs: grep -i error ./build/xcodebuild/build-*.txt
↓
Claude shows only relevant errors (token efficient!)

• iOS (Simulator & Device)
• iPadOS (Simulator & Device)
• visionOS (Simulator & Device)
• watchOS (Simulator & Device)
• tvOS (Simulator & Device)
• macOS (native apps)

• macOS 11+
• Xcode 13+
• Standard macOS tools: xcrun, simctl (included with Xcode)

Verify they're executable:

ls -la ./.claude/scripts/
# Should show -rwxr-xr-x for each script

If not:

chmod +x ./.claude/scripts/*

Check available simulators:

xcrun simctl list

Use correct simulator ID or "booted":

./claude/scripts/capture-logs com.yourapp.vision booted

Verify files exist:

ls -la ./build/logs/ ./build/xcodebuild/

Check the most recent file:

ls -t ./build/logs/logs-*.txt | head -1

This is a minimal, focused project. Suggested improvements:

1. Add platform support - watchOS, tvOS, macOS
2. Create workflow scripts - Combine build + test + deploy
3. Add CI/CD examples - GitHub Actions, GitLab CI
4. Improve error messages - Better diagnostics
5. Add performance tracking - Build time analysis

MIT - Use freely in any project

Igor Makarov's approach to lightweight Xcode automation: https://gist.github.com/igor-makarov/e46c7827493016765d6431b6bd1d2394

This implementation adds:

• visionOS support
• Self-contained installer
• Comprehensive documentation
• Claude Code integration
• Easy team distribution

For issues, questions, or suggestions:

1. Check INSTALLER-USAGE.md FAQ
2. Verify simulator is running: xcrun simctl list
3. Test manually: xcrun simctl spawn booted log stream --predicate "subsystem == 'com.example'"
4. Check ./.claude/building-with-xcode.md troubleshooting section

# Install
bash install-xcode-scripts.sh

# Build
./claude/scripts/xcodebuild -workspace X.xcworkspace -scheme Y build

# Capture logs
./claude/scripts/capture-logs com.yourapp
./claude/scripts/stop-logs

# Search
grep -i error ./build/xcodebuild/build-*.txt
grep -i crash ./build/logs/logs-*.txt

Built for reliable, token-efficient Xcode development with AI assistants.