xctrace-profiler

name

xctrace-profiler

description

Profile Xcode/macOS/iOS apps and Instruments traces with the xctrace-analyzer MCP server. Use for simple requests like "profile this app", "record my app on launch", "find why my app is slow", "check hangs", "find leaks", "inspect allocations", "analyze network", "profile startup", "analyze this .trace", "compare these traces", or "clean up profiling traces"; choose and run the right MCP execution tools without exposing MCP JSON to the user.

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.

Detailed Report Shape

For profiling and trace-analysis reports, default to a full readable diagnostic report, not a short summary. Include everything meaningful the run found: exported hangs, support/export limitations, full-run user-code frames, scoped hang-window frames, requested domain findings, source areas, and recommendations.

Before composing the final user-facing report for profile_running_app, track_running_app, or analyze_trace, read references/report.md and follow its report contract and examples. Only skip it for setup checks, cleanup, template/device listing, trace comparison summaries, or when the user explicitly asks for a brief answer.