Argent

Analyze stored profiling data and return a markdown performance report. Returns { report, reportFile, hotCommitsTotal, hotCommitsShown, sessionFiles }. The report is structured around hot React commits (≥16ms absolute floor) with per-commit render cascades, root cause identification, and a top components table. Raw profiling data is saved to disk with a unique session timestamp for later reload via profiler-load. After presenting the report, ask the user whether to investigate further (drill-down with profiler-cpu-query / profiler-commit-query) or implement fixes and re-profile for comparison. Requires react-profiler-stop to have been called first. Optional annotations param: provide Array<{offsetMs, label}> to annotate commits with the user action that preceded them. Compute offsetMs = tapTimestampMs - startedAtEpochMs where tapTimestampMs is the timestampMs returned by the tap/swipe tool and startedAtEpochMs is returned by react-profiler-start. Use when the profiling session is complete and you need to interpret the collected data. Fails if react-profiler-stop has not been called or no profiling data is stored.

Find a React component's source via tree-sitter AST lookup: returns file path, line number, memoization status (isMemoized, hasUseCallback, hasUseMemo), and 50 lines of source for a named React component. Call this per-finding after react-profiler-analyze to inspect source before proposing a fix. Returns found: false if the component is not found in user-owned code (e.g. lives in node_modules). When several files define a component with the same name (e.g. platform variants like List.tsx and List.web.tsx), returns the primary match and lists the rest under otherMatches[] (file/line/col) — check it before assuming the returned file is the one you meant.

Return a raw Hermes CPU flamegraph summary (top hotspot functions by self-time). FOR DEDICATED CPU INVESTIGATION ONLY — do NOT call this as part of a normal profiling session. Use react-profiler-analyze instead; it covers all React rendering performance analysis. Use when you specifically need to investigate JS CPU hotspots that are NOT tied to React rendering (e.g. regex slowness, cryptography, heavy computations). Call react-profiler-stop first. Reads directly from the stored cpuProfile. Returns a markdown table of the top hotspot functions with self-time, total-time, and location. Fails if react-profiler-stop has not been called or no CPU profile is stored.

Inspect the React fiber tree and return a JSON representation of the component hierarchy. Use when tracing ancestry of a library component or checking for useMemoCache hook (confirms React Compiler is active on a component). Returns a nested JSON tree of fiber nodes with name, tag, actualDuration, selfBaseDuration, and children. Fails if the React DevTools hook is not present or no fiber roots have been committed yet.

Scan the live React fiber tree to collect component render counts and durations. Returns a markdown table of the top re-rendering components. No profiling session required — works on a live connected app. Use when you want a quick snapshot of render counts without a full profiling session. Fails if the React DevTools hook is not present in the runtime or the app is not connected.

Start CPU profiling + React commit capture on the connected Hermes runtime. Delegates React commit capture to the in-app React DevTools backend (ri.startProfiling). If another tool-server already owns the session, returns { already_running: true, owner, stale, how_to_reclaim } without clobbering their data. Pass { force: true } to reclaim a fresh owner's session, but BEFORE OVERTAKING - ask the user for approval first, see relevant skill for guidance. Before calling this, ask the user if they also want native profiling (native-profiler-start) — recommend running both in parallel for a complete picture. After starting, ask the user to perform the interaction to profile, then call react-profiler-stop. Returns { started_at, startedAtEpochMs, hermes_version, detected_architecture } on success, or the already_running payload described above. Fails if the Hermes runtime is not reachable or the Metro CDP connection cannot be established.

Check the state of the React profiler session without side effects. Use after an interruption (debugger disconnect, unexpected error, agent pause) to decide whether to continue with react-profiler-stop, start a new session, or reconnect the debugger. Ownership is verified server-side against this tool-server's in-memory session — no token-threading is required. Returns { session_status, is_running, current_owner, … }. If this tool-server process restarted after react-profiler-start, status will report 'taken_over'; use react-profiler-start { force: true } to reclaim.

Stop CPU profiling and collect the cpuProfile + React commit tree. Reads commit data from the in-app React DevTools backend. Stores results in the ReactProfilerSession for later use by react-profiler-analyze or react-profiler-cpu-summary. Call react-profiler-start first, then exercise the app, then call this. Returns { duration_ms, sample_count, fiber_renders_captured, total_react_commits, hot_commit_indices } summarizing the session. When any commit had fibers whose display name could not be resolved at stop time (typically transient components like modals/tooltips/animations that unmounted before stop), the response also includes { unattributed_ms, unattributed_fiber_count, unattributed_commit_count } — these quantify how much work is not accounted for in the per-component breakdown (the per-commit duration itself remains correct). Fails if no active profiling session exists or the CDP connection was lost during recording.

Install or reinstall an app on the device. The previous installation (if any) is uninstalled first so app data and runtime permissions are cleared. Use for a full reinstall after rebuilding, or to start from a clean app state. Returns { reinstalled, bundleId }. Fails if the app path does not exist or the package does not match the platform (.app for iOS, .apk for Android, .vpkg for Vega).

Terminate then relaunch an app by bundle id / package name. Use when you need a clean in-memory state without a full reinstall. Also refreshes the native-devtools injection before the relaunch (the iOS slice on iOS, the tvOS slice on Apple TV); on tvOS, interaction is focus-driven — use the tv-* tools rather than coordinate taps. Returns { restarted, bundleId }. Fails if the app is not installed.

Set the device orientation to Portrait, LandscapeLeft, LandscapeRight, or PortraitUpsideDown. Use to test layout in a different orientation. Re-run `describe` afterwards — frame coordinates change with the orientation. Returns { orientation }. Fails if the target device is not booted.

Execute multiple device interaction steps in a single call (iOS simulator, Android emulator, Apple TV / Android TV, or Chromium app). Use when you need sequential actions and do NOT need to observe the screen between them (e.g. scrolling multiple times, typing then pressing enter, rotating back and forth). Returns { completed, total, steps } with per-step results. Fails if an unrecognised tool name is used in a step (error returned at that step, execution stops). No screenshot is captured automatically — call screenshot separately after the sequence if needed. ONLY use this when every step is known in advance. If any step depends on the result of a previous one (e.g. tapping a menu item that only appears after a prior tap), use individual tool calls instead. Allowed tools and their args (udid is auto-injected, do NOT include it in args): gesture-tap: { x: number, y: number, clickCount?: number } [ios/android/chromium] gesture-swipe: { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number } [ios/android] gesture-scroll: { x: number, y: number, deltaX?: number, deltaY?: number, durationMs?: number } [chromium only] gesture-drag: { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number } [chromium only] gesture-custom: { events: [{ type: "Down"|"Move"|"Up", x: number, y: number, x2?: number, y2?: number, delayMs?: number }], interpolate?: number } [ios/android] gesture-pinch: { centerX: number, centerY: number, startDistance: number, endDistance: number, endCenterX?: number, endCenterY?: number, angle?: number, durationMs?: number } [ios/android] gesture-rotate: { centerX: number, centerY: number, radius?: number, radiusX?: number, radiusY?: number, startAngle: number, endAngle: number, durationMs?: number } [ios/android] button: { button: "home"|"back"|"power"|"volumeUp…

Start recording the device screen to a video file (h264 mp4, 30fps at the device's native resolution). By default stretches where the screen does not change are trimmed out (see trimStatic), so a long session with only brief activity comes back as a short clip instead of minutes of dead air. By default every tap, swipe, drag, pinch and rotate is drawn into the video as an on-screen touch marker (see showTouches), so the recording shows where each interaction landed. The recording keeps running across other tool calls (every result carries a reminder) until `screen-recording-stop` is called or timeLimitSeconds elapses — immediately after starting, set yourself a reminder/wakeup for the expected end of the recording so it is never left running. Use when the user wants a video of an interaction, animation, or app behavior — for a single still frame use `screenshot` instead. Returns { status: "recording", timeLimitSeconds, outputFile } — the video is retrieved later by `screen-recording-stop`, not by reading outputFile directly. Fails if a recording is already running on the device, the device is not booted, ffmpeg is not installed, or the platform cannot be recorded (tvOS, Chromium, Vega and remote simulators are unsupported).

Stop the screen recording started by `screen-recording-start` and retrieve the video: frame capture ends and ffmpeg finalizes the mp4. Also retrieves the video when the recording already ended on its own (time limit reached, capture process died) — call it even after the cap fired. Use when the interaction being captured is finished, or a tool-result note reminds you a recording is still running. Returns { video, durationMs, wallClockMs?, trimmedMs?, warning? }; video is a downloadable artifact materialized to a local path. When static-frame trimming removed dead air, durationMs is the trimmed video length and wallClockMs/trimmedMs report the real duration and how much was cut. Fails if no recording (running or finished-but-unretrieved) exists for the given udid.

Capture a screenshot of the device screen (iOS simulator, Android emulator, Apple TV simulator, Vega, or Chromium app). Returns { image }; the MCP adapter renders it as a visible image unless the caller passed includeImageInContext: false. Use when you need a baseline image before an interaction or to inspect the current screen state after a delay. Fails if the simulator-server / emulator backend / Chromium CDP is not reachable for the given device.

Compare two PNG screenshots and return a compact visual-diff summary. Accepts saved baseline/current PNG paths, or one saved PNG plus one live full-resolution capture from a device. Always provide udid so the simulator-server dependency can be resolved. Use when stable before/after screenshots exist and the expected result is pixel-visible: layout, spacing, color, typography, image/icon rendering, clipping, overflow, or text rendering. For live captures, set exactly one of captureBaseline or captureCurrent; use baselinePath + captureCurrent for the common visual-regression flow. Returns { summary, diffPath, contextDiffPath }. The summary uses normalized [0,1] screen locations matching describe coordinates; diffPath is the full-size diff image and contextDiffPath is a downscaled image for MCP/agent display. Ignores the fixed top status-bar band for both pixel and OCR text comparisons. Fails if the input sources are invalid, PNG files cannot be read, outputDir cannot be written, or the simulator-server / emulator backend is not reachable.

Grant, deny, or reset a runtime permission for an app without navigating the system Settings UI. Use during test setup to pre-authorize (or explicitly deny) a service before the app asks, or `reset` so the permission dialog appears again on next use. Always per-app: bundleId is required. Permissions: camera, microphone, photos, contacts, notifications, calendar, location, location-always, media-library, motion, reminders. iOS simulator: edits the simulator's TCC store, always per-app. `notifications` is not supported (no iOS equivalent). `reset` is per-app — a device-wide reset is a no-op for existing grants on recent iOS, so it is not offered. `grant location`/`location-always` needs the app already installed (location auth isn't stored in TCC and isn't applied to a bundle id until the app exists) — enforced on local simulators; a remote simulator can't be probed for install state, so ensure the app is installed there first. Other services can be granted before install. Android: changes the mapped `android.permission.*` runtime permissions (reset also best-effort clears the user-set permission flags). The app must be installed and declare them in its manifest; `reminders` has no Android equivalent. Some permission changes terminate the app if it is running (system behavior on both platforms) — set permissions before launching, or relaunch after. Returns { action, permission, bundleId, applied, skipped? }: `applied` lists the platform-level services/permissions actually changed; `skipped` (Android) lists mapped permissions the package manager rejected, e.g. ones the manifest doesn't declare. Fails if nothing could be applied.

Stop all running simulator-server processes (iOS + Android), native devtools services, and Chromium CDP sessions, freeing their resources. Call this when your session ends or the user says they are done. Returns { stopped } — an array of URNs that were shut down. Fails silently if no servers are running.

Stop the Metro bundler process listening on a given port (default 8081). Use when ending a React Native session or when Metro must be restarted. Returns { stopped, port, pids }; stopped=false if no process is found on the port. Fails if the port lookup command times out or the process cannot be killed. This is DESTRUCTIVE — always ask the user for confirmation before calling this tool.

Stop the transport session for a specific device (iOS / Android: simulator-server process; Chromium: CDP WebSocket) and free its resources. Use when you are done interacting with one device but want to keep others running. Returns { stopped, udid }. Fails silently if no session is open for the given id.

Press a TV remote / D-pad button (or a whole path of them) on a TV device — Apple TV (tvOS), Android TV (leanback), or Vega (Fire TV). A TV is navigated with a directional remote, not touch — use this instead of gesture-tap/swipe (which do not apply on a TV). Move focus with up/down/left/right, confirm with select, go back with back/menu, exit with home, and use playPause/rewind/fastForward/next/previous/volumeUp/volumeDown/mute for the corresponding remote keys. (On the Apple TV simulator the media-transport and volume keys are rejected — its HID stack ignores them; they work on Android TV and Vega.) Single press: { button: "down" }. Repeat the same button: { button: "down", repeat: 3 }. Multi-step navigation: pass a path as { button: ["up","right","right","select"] } — it runs in one tool call, far cheaper than separate presses. Read the screen with `describe` before and after to see where focus landed. Returns { pressed, count }.

Apply a pending Argent update. Only call this tool when the user has explicitly consented to updating Argent in this conversation. Use when an update notification indicates a new version is available and the user agrees to update. By default updates the install serving this session; pass `target` to choose global/local/both. Returns { message } with the update status and version info. The tool server will restart automatically after the update. Fails if no update is available or an update is already in progress.

Retrieve captured network (HTTP) requests from the running app. Returns a paginated list of requests with method, URL, status, resource type, size, and duration. Each entry includes a requestId that can be passed to view-network-request-details for full details. On React Native (iOS / Android / Vega) interception is injected into the JS runtime — it captures fetch() calls. On Chromium it reads the browser's native CDP Network domain (the active tab; all request types). Use when inspecting outbound HTTP traffic or debugging API calls in the running app. Fails if the app is not connected (RN) or the device is not reachable (Chromium).

Get full details of a specific network request by its requestId (from view-network-logs). Returns request/response headers (sensitive headers redacted), status, timing, and optionally the response body. Large response bodies are truncated. Use when you need headers, body, or timing for a specific request after listing logs. Returns an error message string if the requestId is not found — use view-network-logs to get valid requestId values.