# Erhe Macos Xcode

> Erhe Macos Xcode is an Agent Skill for development published in the tksuoran/erhe repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Build erhe and read compiler / project diagnostics on macOS through Apple's official Xcode MCP server (mcp__xcode__* tools) driving the live Xcode instance that has the erhe .xcodeproj open. Use for any macOS build, build-error triage, Issue-Navigator query, per-file compiler diagnostics, in-project file navigation, or Apple-documentation (Metal API) lookup. It is NOT a debugger and cannot launch or drive the editor -- no breakpoints / attach / step / callstacks (use erhe-cpp-debugging's lldb path), no scheme or run-destination selection, no way to run the app (use the in-editor MCP server / headless flows). If no Xcode window is open, fall back to scripts/configure_xcode_*.sh + cmake --build.

- Skill name: `erhe-macos-xcode`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/tksuoran/erhe/blob/HEAD/.claude/skills/erhe-macos-xcode/SKILL.md
- Repository: tksuoran/erhe (889 GitHub stars when collected)

## SKILL.md

# erhe macOS builds / diagnostics (Xcode MCP server)

Prefer the `xcode` MCP server (Apple's official Xcode MCP, prefix `mcp__xcode__`)
for build, diagnostics, and in-project file navigation over ad-hoc shell
`xcodebuild` invocations. It drives a *live* Xcode instance that has the erhe
`.xcodeproj` open, so it builds the exact scheme/config the user is working in
and returns structured errors. Verified working against
`build_xcode_vulkan/erhe.xcodeproj` (the Xcode-generated project is one logical
`erhe` tree; C++ sources are reachable, e.g.
`erhe/erhe-executables/editor/main.cpp`).

**Always call `mcp__xcode__XcodeListWindows` first** to get the `tabIdentifier`
(e.g. `windowtab1`) and confirm which workspace is loaded -- every other tool
requires that `tabIdentifier`. If no Xcode window is open, fall back to the
`scripts/configure_xcode_*.sh` + `cmake --build` flow.

## What it CAN do (use these)

- **Build + diagnostics**: `BuildProject` (builds the active scheme, waits for
  completion), `GetBuildLog` (errors/warnings/remarks, filterable by
  `severity` / `pattern` regex / `glob`; reports `buildIsRunning` and
  `buildResult`), `XcodeListNavigatorIssues` (live Issue-Navigator issues incl.
  package/config problems -- can be huge, filter by `severity`/`glob`/`pattern`),
  `XcodeRefreshCodeIssuesInFile` (per-file compiler diagnostics).
- **Project navigation / editing within the Xcode project organization** (NOT
  filesystem paths): `XcodeLS`, `XcodeGlob`, `XcodeGrep` (regex; remember
  double-escaping in the JSON arg, e.g. `\\d`), `XcodeRead`, `XcodeWrite`,
  `XcodeUpdate`, `XcodeMV`, `XcodeRM`, `XcodeMakeDir`, `XcodeGetCurrentFile`.
  For ordinary editing of erhe sources the regular Read/Edit/Write/Grep/Glob
  tools on real filesystem paths are usually simpler; reach for the `Xcode*`
  file tools when you specifically need project-organization semantics (e.g.
  adding a file to the project).
- **Apple docs**: `DocumentationSearch` (semantic search of Apple Developer
  Documentation; useful for Metal API questions).

## What it CANNOT do (do NOT expect VS-MCP-style live debugging)

- **No debugger control whatsoever** -- there is no launch-under-debugger,
  breakpoints, step, continue, attach, callstack, or locals/variable
  inspection. This is the key difference from the Windows Visual Studio MCP
  server. To debug an erhe crash on macOS you need lldb directly (see the
  `erhe-cpp-debugging` skill), plus `logs/log.txt`.
- **No scheme / run-destination / launch-target selection** -- all
  build/test/run tools act on whatever scheme is *currently active* in the
  Xcode UI (here: `editor`). You cannot switch scheme or run target via MCP;
  ask the user to set it in Xcode.
- **No way to launch and drive the running editor app.** The only "run" tools
  are `RunAllTests` / `RunSomeTests` (active scheme's XCTest test plan --
  erhe's `editor` scheme has 0 XCTest tests, so not useful here),
  `ExecuteSnippet` (builds & runs a *Swift* snippet and returns its `print`
  output -- N/A to a C++ project), and `RenderPreview` (SwiftUI preview
  snapshots -- N/A). To actually run/inspect the editor, use the build scripts
  + the in-editor MCP server / headless screenshot flows.

**Bottom line:** on macOS the Xcode MCP server is the preferred tool for
*building and reading diagnostics* (and Apple-docs lookup), but it is NOT a
debugger and cannot launch or drive the editor. For runtime behavior use
`logs/log.txt` and the in-editor MCP server; for live debugging use lldb via
the `erhe-cpp-debugging` skill.

---

Source: https://www.openparable.com/skill/development/erhe-macos-xcode (OpenParable). Cite the canonical URL above.
