tomevault-io dd-sdk-ios Xcode File Management
Overview
The dd-sdk-ios project is both an SPM package and an Xcode workspace with .pbxproj files. SPM builds discover files automatically, but Xcode does not — it requires explicit registration in .pbxproj. The Xcode MCP server (available from Xcode 26.3+) handles this automatically. Always use it.
Prerequisites
The Xcode MCP server requires Xcode 26.3+ and must be enabled in Claude Code settings. Verify it's active by checking that XcodeListWindows is available. If not, stop and ask the user to enable the Xcode MCP server before proceeding with file operations.
The Rule
Never use Write, Bash mv/mkdir/rm, or Edit for file creation, deletion, or movement in this project.
Use Xcode MCP tools instead — they update the filesystem AND the .pbxproj in one atomic operation.
Target Membership
Target membership is implicit — Xcode MCP infers the target from the navigator path where the file is placed. A file added under DatadogLogs/ is automatically assigned to the DatadogLogs target. No explicit target specification is needed.
Quick Reference
| Operation | Use This Tool | Never Use |
|---|---|---|
| Create file | XcodeWrite |
Write, Bash touch/cat |
| Delete file | XcodeRM |
Bash rm |
| Move / rename | XcodeMV |
Bash mv |
| Create directory/group | XcodeMakeDir |
Bash mkdir |
| Read file | XcodeRead |
(either is fine) |
| Search files | XcodeGlob, XcodeGrep |
(either is fine) |
Common Rationalizations — All Wrong
| Excuse | Reality |
|---|---|
| "SPM auto-discovers files, pbxproj doesn't matter" | The Xcode workspace has .pbxproj files. They must stay in sync or Xcode breaks. |
| "It's faster to use bash" | A file invisible to Xcode causes build failures and confuses teammates. |
| "I'll update pbxproj manually after" | pbxproj is binary-adjacent XML; manual edits cause merge conflicts and corruption. |
| "The file is just temporary" | Temporary files still break the build if Xcode can't see them. |
Example
# ✅ Add a new source file
XcodeWrite(
tabIdentifier: <tab>,
filePath: "DatadogLogs/Sources/LogBatcher.swift",
content: "..."
)
# → Creates file on disk AND registers it in pbxproj + target membership
# ✅ Move a file
XcodeMV(
tabIdentifier: <tab>,
sourcePath: "DatadogLogs/Sources/LogBatcher.swift",
destinationPath: "DatadogLogs/Sources/Batching/LogBatcher.swift"
)
# → Moves file on disk AND updates pbxproj reference
# ❌ Wrong — file created on disk but invisible to Xcode
Write(file_path: ".../DatadogLogs/Sources/LogBatcher.swift", content: "...")
Getting the tabIdentifier
XcodeListWindows() # → returns tabIdentifier for open workspace
Path Format
Xcode MCP uses project navigator paths, not filesystem paths. Use XcodeLS to discover them:
XcodeLS(tabIdentifier: <tab>, path: "DatadogLogs")
# → ["ConsoleLogger.swift", "Feature/LogsFeature.swift", ...]
# Note: paths are relative to the Xcode group, not the filesystem root
To create DatadogLogs/Sources/Foo.swift on disk, use the navigator path DatadogLogs/Foo.swift.
After File Operations
After adding files to a module, verify the build still works:
BuildProject(tabIdentifier: <tab>)
Source: DataDog/dd-sdk-ios — distributed by TomeVault.