A reference guide listing known problems and configuration rules for an Xcode and Bazel MCP project. Xcode is Apple's development environment, Bazel is a build system, and MCP connects tools to AI agents.

It explains test and coverage configuration, rebuilding generated files, simulator limitations and resolution, Apple app-bundle locations, and current device-listing commands.

It prevents common setup, build, simulator, device, and logging mistakes that may otherwise take time to diagnose.

gotchas — Agent by DebugSwift

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add agents/debugswift/xcodebazelmcp/gotchas

Clone the repo

git clone --depth 1 https://github.com/DebugSwift/XcodeBazelMCP

Made for: Codex.

Per session 0 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 1,503 The whole file, excluding the scripts and references it only reads on demand.

Security scan B 1 finding. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00000	$0.01503
Opus 5	$0.00000	$0.00751
Sonnet 5	$0.00000	$0.00301
Haiku 4.5	$0.00000	$0.00150

Measured yesterday against content hash f6989ab7fcce, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade B, and why

gotchas scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Asks for rootmediumPrivilege escalation

A mod that escalates privileges can change anything on the machine, not only the project.

- **Screenshot limitation**: No `devicectl` subcommand exists for screenshots. `idevicescreenshot` fails with "Invalid service" (iOS 17+ DDI change). Workaround: `sudo pymobiledevice3 remote tunneld` in background → `pym

.agents/agents/gotchas.md · 64 lines

How it starts

The opening of the file, as written. The whole thing — 64 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Gotchas & Known Issues

Build & Config

Don't hardcode --config=test in test/coverage commands — not all projects define that Bazel config. Users pass it via configs array if needed.
dist/ must be rebuilt after source changes — npm run build regenerates it.
npm run lint uses ESLint 9 flat config — --ext .ts flag is invalid. Just eslint src.
scaffold.ts: moduleBazel always generates with needsAppleRules = true — the template parameter was removed since it was never actually used.

Simulator

xcrun simctl io does NOT support UI interaction commands (tap, swipe) — only screenshots, video recording, IO port enumeration.
rules_apple places .app bundles inside <target>_archive-root/Payload/ — findAppBundle must search recursively.
Simulator tools (set_simulator_location, set_simulator_appearance) should use resolveSimulator() to support both simulatorId and simulatorName.
The Simulator.app window position matters for CGEvent — events are posted to absolute screen coordinates.

Device

xcrun devicectl list devicePairs is deprecated/invalid in modern Xcode. Use xcrun devicectl list devices.
listDevicePairs in core/devices.ts is misleadingly named — it runs devicectl list devices, same as listDevices.
iOS 17+ / macOS 15+: Apple replaced lockdownd/usbmuxd with CoreDevice (remoted). devicectl is the only CLI that works reliably. idevicescreenshot, idevicesyslog, and pymobiledevice3 (without tunneld) cannot connect to devices — even over USB.
Screenshot limitation: No devicectl subcommand exists for screenshots. idevicescreenshot fails with "Invalid service" (iOS 17+ DDI change). Workaround: sudo pymobiledevice3 remote tunneld in background → pymobiledevice3 developer dvt screenshot <path> --udid <UDID>.
Log limitation: idevicesyslog cannot connect to iOS 17+ devices. startDeviceLogCapture() now tries pymobiledevice3 syslog live first (with 1.5s early-exit detection for failures), falling back to idevicesyslog for older devices.
Process termination: devicectl device info processes only returns executable (file:// URL) and processIdentifier — no bundleIdentifier. Must lookup app executable name via devicectl device info apps first, then match by executable path.
Device names with Unicode: Smart quotes in device names (e.g., Matheus\u2019s iPhone) must be normalized to ASCII apostrophes before string comparison.
Build for device: buildCommandArgs() must exclude simulator-specific flags (--ios_simulator_device, sim_arm64) when platform === 'device'. Device builds use --ios_multi_cpus=arm64.
Implicit Bazel targets: findAppBundle() handles both //pkg:target (explicit) and //pkg (implicit, where target name = last path component).

Read the full file on GitHub · 64 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday First seen · 64 lines · 0 tokens per session scan B f6989ab7fcce

Subscribe to this mod's changes

gotchas is an agent published in the GitHub repository DebugSwift/XcodeBazelMCP (7 stars, last pushed 1mo ago), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 1,503 tokens. A static security scan graded it B with 1 finding (asks for root). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Data and AI Debugging Testing bazel ios lldb macos mcp mcp-server

apple-neural-performance-expert

Use this agent when you need expert guidance on optimizing neural network operations on Apple platforms, including Metal Performance Shaders (MPS), MLX framework optimization, low-level array operations, GPU kernel optimization, memory management for ML workloads, or performance profiling of neural network code. This…

FluidInference/FluidAudio · 417 tokens

code-search-ast-grep

Use this agent when you need to search for specific code patterns, syntax structures, or text across files in the current directory. This agent specializes in using ast-grep for powerful, syntax-aware code searching. Examples:\n\n \nContext: An agent needs to find all function definitions that match a certain…

FluidInference/FluidAudio · 344 tokens

gotchas