Record and analyze CPU performance using Time Profiler. Returns: Top CPU hotspots with severity classification and actionable summary. Pass trace_path to re-analyze an existing trace without re-recording.

Record and analyze SwiftUI view performance. Returns: View body evaluation counts, excessive re-renders, and duration per view. Best used while navigating through the app. Pass trace_path to re-analyze an existing trace.

Record and analyze memory allocations. Returns: Allocation counts by category, total memory, largest allocators. Pass trace_path to re-analyze an existing trace.

Record and analyze animation hitches and main thread hangs. Returns: Hang events by severity, worst hangs with backtraces. Best used during scrolling or animations. Pass trace_path to re-analyze an existing trace.

Record and analyze app launch performance. Returns: Total launch time, launch type (cold/warm/resume), phase breakdown, severity against Apple's guidelines. IMPORTANT: Use launch_path to launch the app — attaching to a running process won't capture the launch. Pass trace_path to re-analyze an existing trace.

Record and analyze energy usage using Energy Log. Returns: Energy impact scores (0–20 scale), per-component breakdown (CPU, GPU, network, display), thermal state. Best results on physical devices. Pass trace_path to re-analyze an existing trace.

Record and detect memory leaks using the Leaks template. Returns: Leaked object types, sizes, responsible libraries, and backtraces. The Leaks instrument takes periodic heap snapshots — longer recordings improve detection. Pass trace_path to re-analyze an existing trace.

Record and analyze HTTP network traffic using the Network template. Returns: Request counts, response times, error rates, per-domain breakdown, slowest requests. Pass trace_path to re-analyze an existing trace.

Record a trace with any Instruments template and return the raw table of contents. Use this for templates without a dedicated parser (System Trace, File Activity, etc.). You can then use analyze_trace to export specific tables.

Check if Instruments (xctrace) is available on this system and return version info

List all available Instruments profiling templates (Time Profiler, SwiftUI, Allocations, etc.)

List all available devices and simulators that can be profiled

List all available individual instruments that can be combined into custom recordings

Export and analyze a specific table from an existing .trace file. Use after profile_raw to drill into specific data tables. First call with toc=true to see available tables, then call with xpath to get data.

Add debug symbols to a trace file so function names are readable instead of memory addresses. Run this if profile results show hex addresses instead of function names.

Run a comprehensive performance audit by recording multiple profiles in sequence. Records: Time Profiler + Animation Hitches + Leaks + Energy Log + Network for a full health check. Returns a combined report with actionable findings and an overall severity. Total recording time = 5x duration.

Save, compare, list, or delete performance baselines to track regressions over time.

• save: Store profile results as a named baseline (pass the JSON output from any profile tool)

• compare: Diff current results against a saved baseline — shows deltas and regression/improvement status

• list: Show all saved baselines

• delete: Remove a saved baseline

Generate a shareable Markdown performance report from profile results. Pass the JSON output from one or more profile tools. Returns formatted Markdown suitable for PRs, Slack, documentation, or stakeholder updates.

List all booted iOS simulators and their installed user apps. Returns: Device names, UDIDs, runtime versions, and installed app bundle IDs. Use this to discover what's running before profiling.

Launch an app by bundle ID on a booted simulator. Returns the process ID (PID) of the launched app.

Terminate a running app on a simulator.

Open a URL or deep link on a simulator. Use this for app navigation — simctl does not support direct tap/swipe. The app must register the URL scheme in its Info.plist.

Send a simulated push notification to an app on a simulator. Constructs an APS payload from title/body, or accepts a full custom payload.

Take a screenshot of a simulator's screen. Saves as PNG. Returns the file path to the saved screenshot.

Toggle the simulator between light and dark mode. Useful for testing appearance-sensitive performance (e.g., dark mode rendering).

Set simulated GPS coordinates on a simulator. Useful for profiling location-dependent features.

Start recording an Instruments trace and return immediately. The user interacts with the app manually while recording runs in the background. Call stop_profiling when done to end the recording and get parsed results.

This is the recommended workflow for profiling real user interactions:

1. start_profiling → agent starts recording

2. User scrolls, taps, navigates in the app

3. stop_profiling → agent stops recording, parses trace, returns performance data

Max recording time is 5 minutes (safety limit). Recording stops automatically if not stopped manually.

Stop an active recording started by start_profiling. Sends SIGINT to xctrace, waits for the trace to be saved, then parses and returns structured results. Returns the same parsed performance data as the profile_* tools.

Record an Instruments trace WHILE executing a scenario on a simulator. This is the primary tool for profiling real user flows — it launches your app, runs interaction steps, and records performance data throughout.

Steps execute sequentially after xctrace starts recording. Supports both simctl steps (deep links, push, appearance, location) and UI automation steps (tap, type_text, swipe, gesture, long_press, snapshot_ui) powered by AXe CLI. UI steps require AXe: brew tap cameroncooke/axe && brew install axe

Returns: Parsed profile results + screenshots taken + scenario execution log.

Get the accessibility hierarchy of a simulator screen. This is the key tool for understanding what's on screen — returns element roles, labels, identifiers, values, and frame coordinates. Use it to find elements before tapping or swiping.

Requires AXe CLI: brew tap cameroncooke/axe && brew install axe

Tap a UI element on the simulator by accessibility id (most reliable), label, or x/y coordinates. At least one targeting method must be provided. Prefer accessibility id when available — use ui_snapshot to discover them.

Requires AXe CLI: brew tap cameroncooke/axe && brew install axe

Type text into the currently focused field on the simulator. Tap a text field first with ui_tap to focus it, then use this to type.

Requires AXe CLI: brew tap cameroncooke/axe && brew install axe

Swipe between two points on the simulator screen. Use ui_snapshot to get coordinates, then swipe between them. For common gestures like scrolling, prefer ui_gesture instead.

Requires AXe CLI: brew tap cameroncooke/axe && brew install axe

Perform a preset gesture on the simulator. Available presets: scroll-up, scroll-down, scroll-left, scroll-right, swipe-from-left-edge, swipe-from-right-edge, swipe-from-top-edge, swipe-from-bottom-edge.

Requires AXe CLI: brew tap cameroncooke/axe && brew install axe

Long press (touch-and-hold) at coordinates on the simulator. Use ui_snapshot to find the target element's frame coordinates.

Requires AXe CLI: brew tap cameroncooke/axe && brew install axe

Navigate deeper into profiling data from a previous profile result. Use the traceId returned by any profile_* tool to investigate further.

CPU traces: Pass a function name to see its callers (who calls it), callees (what it calls), and the heaviest execution path. Use "hottest" to auto-select the most expensive function.

Other templates: Pass a search term (category, domain, view name, leak type) to see full detail for matching rows that were truncated in the initial summary.

Examples: drill_down(trace_id: "t_abc123", target: "CoreData.executeFetchRequest") drill_down(trace_id: "t_abc123", target: "hottest") drill_down(trace_id: "t_abc123", target: "api.example.com")

List profiling traces available for investigation with drill_down. Shows trace IDs, templates, and timestamps from this session's profile_* calls.