The One File I Keep Out of Claude Code's Reach: project.pbxproj

Narrowing the entrance to one script

The first thing I scripted was adding the Crashlytics dSYM upload as a Run Script phase. The SPM migration had broken the reference that pointed at ${PODS_ROOT}, and crashes had been arriving unsymbolicated for several days.

Idempotence was the whole game. If running it twice does not land in the same state, a script is more dangerous than a hand edit, not less.

#!/usr/bin/env ruby
# add_run_script.rb — adds a Run Script phase, idempotently
#   gem install xcodeproj
#   ruby add_run_script.rb MyApp.xcodeproj MyApp
require "xcodeproj"
 
PHASE_NAME = "[Dolice] Upload dSYMs"
 
project_path, target_name = ARGV
abort("usage: add_run_script.rb <project.xcodeproj> <target>") unless project_path && target_name
 
project = Xcodeproj::Project.open(project_path)
target  = project.targets.find { |t| t.name == target_name }
abort("target not found: #{target_name}") unless target
 
# Look the phase up by name. Looking it up by UUID misses phases created
# on another machine, and you end up adding a second copy.
phase = target.shell_script_build_phases.find { |p| p.name == PHASE_NAME }
phase ||= target.new_shell_script_build_phase(PHASE_NAME)
 
phase.shell_path = "/bin/sh"
phase.shell_script = <<~SH
  set -euo pipefail
  # After the SPM move this lives in DerivedData, not under Pods
  BIN="${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"
  test -x "$BIN" || { echo "warning: crashlytics run not found at $BIN"; exit 0; }
  "$BIN"
SH
phase.input_paths = ["${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}"]
phase.run_only_for_deployment_postprocessing = "0"
 
# Pin the position too. Left implicit, the phase can run before artifacts exist.
target.build_phases.delete(phase)
target.build_phases << phase
 
project.save
puts "ok: #{target_name} -> #{PHASE_NAME}"

Everything hinges on the three details below.

1. Match the existing phase by name, not UUID. UUIDs differ per machine, so a UUID lookup silently misses phases added elsewhere
2. Overwrite the script body every run. Appending leaves stale lines behind, mixed in with the new ones
3. Move the phase to the end explicitly. An implicit position eventually runs before the build artifacts are there

I do let Claude Code write and run this script. What it is trusted with is authoring and executing a script — not editing the project file. That distinction pays off later.

Judge a change by whether the inventory matches, not by whether it opens

Scripting does not eliminate shifted meaning. Since it does not, I built something to detect it.

project.pbxproj is an OpenStep property list, so macOS plutil converts it to JSON as-is. No custom parser is needed to pull out the per-target file lists.

#!/usr/bin/env python3
"""pbx_inventory.py — lists files by target and build phase
 
    python3 pbx_inventory.py MyApp.xcodeproj > before.txt
    # now make whatever change touches the project file
    python3 pbx_inventory.py MyApp.xcodeproj > after.txt
    diff before.txt after.txt
"""
import json
import subprocess
import sys
from pathlib import Path
 
PHASES = {
    "PBXSourcesBuildPhase": "Sources",
    "PBXResourcesBuildPhase": "Resources",
    "PBXFrameworksBuildPhase": "Frameworks",
}
 
 
def load(xcodeproj: Path) -> dict:
    pbx = xcodeproj / "project.pbxproj"
    # plutil reads the OpenStep format directly. Send the conversion to stdout
    # and never back to the file itself — the "-o -" is the important part.
    raw = subprocess.run(
        ["plutil", "-convert", "json", "-o", "-", str(pbx)],
        capture_output=True, check=True,
    ).stdout
    return json.loads(raw)["objects"]
 
 
def path_of(objects: dict, ref: str) -> str:
    """Walk up through parent groups to something close to a repo-relative path"""
    node = objects.get(ref, {})
    name = node.get("path") or node.get("name") or ref
    for key, value in objects.items():
        if value.get("isa") == "PBXGroup" and ref in value.get("children", []):
            parent = path_of(objects, key)
            return f"{parent}/{name}" if parent else name
    return name
 
 
def main(xcodeproj: str) -> int:
    objects = load(Path(xcodeproj))
    rows = []
    for target in (o for o in objects.values() if o.get("isa") == "PBXNativeTarget"):
        for phase_ref in target.get("buildPhases", []):
            phase = objects.get(phase_ref, {})
            label = PHASES.get(phase.get("isa"))
            if not label:
                continue
            for build_file_ref in phase.get("files", []):
                file_ref = objects.get(build_file_ref, {}).get("fileRef")
                if not file_ref:
                    continue
                rows.append(f"{target['name']}\t{label}\t{path_of(objects, file_ref)}")
    # Ordering follows UUIDs and shifts every run, so always sort before printing
    for row in sorted(set(rows)):
        print(row)
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

Three columns come out: target, phase, path. Take one before your work and one after, run diff, and only the unintended arrivals and departures remain.

$ diff before.txt after.txt
< BeautifulWallpapers	Resources	Resources/Images/ldpi/placeholder.png

The accident I opened with was exactly that line disappearing. Invisible while I read hundreds of diff lines, obvious the moment the same change was folded into three columns — less information turned out to be what made it findable.

Where I stumbled

The parent-group walk in path_of scans every object once per reference. On a larger project that gets noticeably slow, so in daily use I precompute a child-to-parent map instead. The version above favours readability.

There is a bonus, too. If plutil fails outright, the project file is genuinely broken. This inventory aims at the silent failure, and picks up the loud one on the way past.

Declare the boundary on the Claude Code side

A rule that lives only in my head collapses on a busy day, so I wrote it into the settings file.

{
  "permissions": {
    "deny": [
      "Edit(**/*.xcodeproj/project.pbxproj)",
      "Write(**/*.xcodeproj/project.pbxproj)",
      "Edit(**/*.xcworkspace/contents.xcworkspacedata)"
    ],
    "allow": [
      "Bash(ruby scripts/xcode/*.rb:*)",
      "Bash(python3 scripts/xcode/pbx_inventory.py:*)"
    ]
  }
}

Writing both deny and allow is the point. Blocking edits alone leaves sed and python3 -c as open routes — unless the intended road is marked, a narrow path forms beside the one you closed.

Verify the setting by behaviour once it is in place. A single mistyped key is ignored in silence by most tooling. I asked for a one-line change to project.pbxproj and confirmed the refusal before trusting it. On counting up what you have already permitted, I wrote that out separately in Take Inventory of What You Allowed with Don't Ask Again in Claude Code.

The same reasoning applies to reads. Project files are enormous relative to how much they tell you, and they crowd out context. My criteria for excluding them are in One generated file outweighed all 70 hand-written source files, so I redrew what Claude Code may read.

One more failure mode, from the sync folder

This one is not Xcode's fault, but I hit it the same week, so it belongs here.

My sources live under Dropbox. If a build starts right after the project file is saved, the sync client can pick up an intermediate state and leave something like project.pbxproj (conflicted copy) beside it. Xcode still holds the original, so nothing happens that day. It happens days later, when nobody can say which one is current.

# Keep build artifacts out of sync (this attribute is Dropbox-specific)
for d in build DerivedData "*.xcodeproj/project.xcworkspace/xcuserdata"; do
  find . -type d -path "./$d" -print0 2>/dev/null \
    | xargs -0 -I{} xattr -w com.dropbox.ignored 1 {}
done
 
# Surface any conflicted copies that already exist
find . -name "*conflicted copy*" -o -name "*競合コピー*" | sort

I apply the xattr once, right after creating a working directory. It is now part of what I run immediately after cloning a new app repository.

Where a direct edit is still fine

A rule that forbids everything does not survive contact with a deadline. Three cases stay exempt for me.

1. Anything under xcuserdata and similar paths that git never tracked
2. Adding a single new source file. The Xcode GUI is faster, and the inventory diff reads as one line
3. Rescuing a project that is already broken. Getting it to open comes first; shifted meaning can be recovered later by the inventory

Conversely, what I would recommend always routing through a script is any change touching build phases, target membership, or build settings. Those three are precisely where the silent breakage is born.

Where the line sits now

Roughly half a year in, the number of last-minute scrambles before a release has dropped noticeably. Not because the agent got more accurate. Because there is now one mechanism outside the build that notices when something broke.

I have started reasoning the same way about AdMob configuration and store listing metadata — rather than blocking the change, reshape it so a machine can confirm the change landed as intended. Whatever resists that reshaping is what moves out of reach.

If you want one thing to try today, run pbx_inventory.py once and keep the output as before.txt. The next time you touch the project file, having that single page changes what you can see.

Thank you for reading. I am still redrawing this line myself, and I suspect the third exception will narrow further before long.