xctrace-profiler

Xcode Trace Profiler

Goal

Be the user-facing profiler for xctrace-analyzer. Users should ask in plain language; do not ask them to know MCP tool names or JSON. Choose the workflow, call the MCP execution tools, and report what xctrace could and could not export.

Simple Prompts

• "Profile this app."
• "Profile this app for hangs."
• "Find why this app is slow."
• "Check this build for leaks and allocation churn."
• "Analyze network activity."
• "Launch the app and profile startup."
• "Record my app on launch."
• "I will launch MyApp; record it for 60 seconds when it appears."
• "Analyze this trace."
• "Compare these two traces."

What It Can Track

• CPU and Time Profiler bottlenecks
• Hangs, freezes, stutters, microhangs, and severe hangs
• Top User-Code Frames that attribute samples to app binaries
• Leaks and allocation churn when Xcode exports usable rows
• Network requests, failures, transfer volume, and top hosts when HAR or CFNetwork data is exportable
• Energy / Power Profiler data where Xcode supports it, mainly iOS/iPadOS
• Existing .trace files, optional dSYM symbolication, scoped timeRangeMs analysis, and Time Profiler regressions
• Safe cleanup of generated .trace bundles after the user is done inspecting them

Workflow

1. Classify the request.

   • Cleanup / delete traces: call cleanup_traces.
   • Existing .trace: call analyze_trace.
   • Baseline/current or regression: call compare_traces.
   • Explicit single template such as Leaks, Allocations, Network, or Time Profiler: call track_running_app.
   • Broad, vague, hangs, CPU, leaks, memory, allocations, network, energy, startup, or "profile this app": call profile_running_app.

2. Establish the target.

   • Inspect the project for obvious Xcode targets, schemes, bundle names, app products, or trace paths before asking.
   • If shell access is available and the app may already be running, discover candidate PIDs and prefer the exact PID.
   • For already-running apps, use attach-by-PID immediately, especially when several processes share a name. Do not ask launch-prep questions for active app profiling.
   • Use launch mode only for explicit startup/cold-launch profiling.
   • For launch or startup prompts such as "get ready, I will launch my app", "record my app on launch", "profile when I launch it", or "cold launch profile", first establish what process should be watched.
   • If exactly one likely app target is discoverable, announce it and start manual-launch observation immediately: "I found MyApp. I'm watching for its PID now; launch it when ready."
   • If the app identity is missing or ambiguous, ask one concise question for the app name, bundle id, app path, or scheme, and offer observation as the easy fallback: "I can also start observing now and you can launch it after I say I'm watching."
   • Once manual launch observation starts, poll every 200-500 ms for up to 60 seconds while the user launches the app. As soon as one valid PID is visible, call the recording tool with target: "attach", processName set to that exact PID, and durationSeconds set from the user's requested duration so recording starts as close to launch as possible.
   • While observing, a short status such as "I'm watching for MyApp now; launch it when ready." is enough. Keep polling after sending that status.
   • If multiple matching PIDs appear during observation, prefer the newest app executable PID over helper processes. If ambiguity remains, keep observing briefly for a stable main-app PID; ask only if the candidates are still ambiguous.
   • If no PID appears before the observation timeout, tell the user no launch was detected and ask them to relaunch or provide the exact app name, bundle id, or PID.
   • If no target can be discovered, ask one concise question for the app path, scheme, bundle id, process name, or PID.
   • Infer userBinaryHints from the app, scheme, executable, module, or bundle name.