lynx-devtool

Agent Lynx DevTool Skill

This skill allows you to interact with Lynx applications running on connected devices (Android, iOS, Desktop) using the agent-lynx CLI.

Usage

Use the agent-lynx CLI. The published package is agent-lynx. This package, @lynx-js/skill-lynx-devtool, is the canonical source of this Skill's instructions and resources. agent-lynx depends on it and reads it directly for skills list/get. A compatibility launcher also keeps the historic one-shot npx -y @lynx-js/skill-lynx-devtool invocation working.

The programmatic API is exported from agent-lynx/connector. This entry re-exports everything from @lynx-js/devtool-connector, @lynx-js/devtool-connector/transport, and @lynx-js/devtool-connector/streams, and also provides daemon-only createDefaultTransports() and createDefaultConnector() helpers. The helpers use one DaemonTransport so independent scripts share the daemon-owned device connection. Construct a Connector with explicit transports only when intentionally testing a non-daemon path.

Online CLI commands follow the same daemon-only default. --no-daemon is an explicit escape hatch that replaces the daemon with direct Android, iOS, OpenHarmony, and Desktop transports for that invocation. The built-in headless runtime remains daemon-only. ADB_SERVER_HOST and ADB_SERVER_PORT configure only this direct mode. Daemon mode ignores them with a stderr warning.

The agent-lynx CLI is normally available on PATH. If command -v agent-lynx fails, use npx instead:

npx --yes agent-lynx <command>

This published skill does not ship a local CLI entry script. Use:

agent-lynx <command>

Note: Most command outputs are JSON. You can use jq or Node.js to process the data.

Discover Built-in Skills

The installed @lynx-js/skill-lynx-devtool dependency provides the lynx-devtool skill. Discover it or load its complete instructions with:

agent-lynx skills

skills list reads each name and description directly from that package's SKILL.md YAML frontmatter. skills get returns the selected Markdown body and recursively lists regular files under references/, assets/, and examples/ when those directories exist. Symlinks and build output are not included. The stable name is lynx-devtool.

Snapshot Workflow

Snapshot refs live in daemon memory across CLI invocations. Do not pass --no-daemon to snapshot, tap, long-press, fill, clear, scroll, get text, get style, wait, or screenshot. wait uses the daemon's SSE command route; the other snapshot commands use POST /command/<action>.

screenshot --annotate refreshes and caches snapshot refs, then draws numbered labels directly into one JPEG. Label [N] maps to ref @eN, so an agent can inspect the image and immediately use the matching ref. The image labels a sparse actionable subset of the visible refs: direct action targets, editable fields, explicit test targets, and scroll containers. Generic layout and text refs remain available in the cached snapshot without cluttering the image. Viewport-sized scroll containers use a corner badge instead of a full-frame border. With --json, the result also carries the complete fresh snapshot used by this same ActionCore call, so consumers can compare the image and refs without issuing a second refresh. Pixel mapping uses the screencast frame's logical-size metadata separately from the potentially inset snapshot viewport; the command fails instead of guessing when that metadata is unavailable. Do not combine --annotate with --fullscreen; use unannotated screenshot --fullscreen or the legacy take-screenshot --fullscreen command instead. See Annotated Screenshots Reference.

Programmatic connector imports require a project dependency:

This project-local install is needed only for connector workflows, not for CLI-only use through the agent-lynx CLI on PATH or npx.

Use as a Library

If you want to drive Lynx DevTool directly from JavaScript instead of shelling out to the CLI, import from agent-lynx/connector.

For fuller programmatic workflows, see Library Usage Reference and Programmatic Debugging Example.

You can also construct the connector manually if you intentionally need custom, non-daemon transports:

Global Options

• -h, --help: Display help for command.
• --no-daemon: Bypass the shared daemon and use direct device transports for this invocation. Stop the daemon first if it may own a connection to the same DebugRouter target.

Note: Each subcommand supports the --help flag (e.g. agent-lynx cdp --help). Use this to view the full list of available arguments and their descriptions.

Commands

1. List Clients

List all available Lynx clients (apps with DevTool enabled).

2. Wait For Client

Wait until a client is available.

• --client-name <name>: Optional package/app name to wait for. Matches AppProcessName, bundleId, bundleName, or App. If multiple clients match, all matching clients are returned. If omitted, the first non-headless client is returned. Output is always a JSON array.
• --timeout <seconds>: Maximum seconds to wait. Defaults to 30.
• --interval <seconds>: Seconds between discovery attempts. Defaults to 1.

3. List Sessions

List all active debugging sessions. A session corresponds to a specific Lynx view or context.

4. Send CDP Command

Send a Chrome DevTools Protocol (CDP) command to a specific session.

Note that Lynx only supports a part of the standard CDP command. LynxView note: when the target session is a LynxView, you MUST read Supported CDP Methods before sending a CDP command. WebView note: when the target session is a WebView (for example type: "web" or an HTTP/HTTPS URL), use the standard Chrome DevTools Protocol documentation for CDP method names, parameters, and enable prerequisites. The local references/cdp pages focus on LynxView support and Lynx-specific extensions, which may return method not found on WebView targets.

• -m, --method <method>: The CDP method name (e.g., DOM.getDocument, Page.reload).
• -c, --client <clientId>: (Optional) The Client ID. If omitted, uses the first available client.
• -s, --session <sessionId>: (Optional) The Session ID. If omitted, uses the latest session (with the largest session ID).
• --thread <thread>: (Optional) Target VM thread, background or main. Defaults to background.
• [params]: (Optional) JSON string of parameters for the command.

When --thread main is used, only Debugger.*, Runtime.*, HeapProfiler.*, and Profiler.* methods are supported.

Example:

5. Evaluate JavaScript

Evaluate a JavaScript expression. On the background VM, the current app's lynx and nativeLynx objects are available as local variables. Expressions targeting the main VM are sent unchanged.

• <expression>: JavaScript expression to evaluate.
• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --thread <thread>: (Optional) Target VM thread, background or main. Defaults to background. Only background expressions are wrapped to expose lynx and nativeLynx; main-thread expressions are sent unchanged.
• The command requests results by value by default. Engines that support returnByValue serialize ordinary JSON-like objects into result.value; current Android Lynx runtimes may ignore it for object values and still return an objectId. Use JSON.stringify(lynx.__globalProps) when JSON output is desired. Use --no-return-by-value to deliberately receive an objectId for later Runtime.getProperties or Runtime.callFunctionOn requests. --return-by-value remains accepted as an explicit form of the default.
• --silent, --context-id, --throw-on-side-effect, --generate-preview, --object-group, --await-promise, --include-command-line-api: Optional evaluation parameters. Engine support varies.

6. Send App Command

Send an App-level command.

• -m, --method <method>: The App method name (e.g., App.openPage).
• -c, --client <clientId>: (Optional) Client ID.
• [params]: (Optional) JSON string of parameters.

You MUST read Supported App Methods before sending an App command.

7. Open URL

Open a specific URL in the Lynx app.

• <url>: The URL to open.
• -c, --client <clientId>: (Optional) Client ID.

Example:

8. Get Console

Capture console logs from the device.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --offset <number>: Skip N messages.
• --limit <number>: Limit number of messages.
• --include-stack-traces: Include stack traces for non-error messages.
• --level <levels>: Filter log levels (e.g., error,warning).
• --thread <thread...>: Target VM thread(s): background or main. If omitted, both threads are collected by default.

9. Get Sources

List all parsed scripts. This is useful for finding script IDs to use with other commands (e.g., Debugger.getScriptSource). The command automatically fetches all currently loaded scripts.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.

10. Inspect

Print the DevTool inspector URL served by the connector daemon for a client/session pair. Open the printed URL in a browser to attach a graphical inspector to the same session the CLI targets.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --port <port>: (Optional) Daemon port. Defaults to 21783.

11. Agent Screenshot

Capture through ActionCore, optionally drawing fresh snapshot refs directly into the resulting JPEG.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --annotate: (Optional) Refresh refs and draw [N] labels, where [N] maps to @eN.
• --fullscreen: (Optional) Capture fullscreen instead of LynxView. Cannot be combined with --annotate.
• -o, --output <path>: (Optional) JPEG output path.
• --json: (Optional) Return the path, image dimensions, complete fresh snapshot, and annotation metadata.

This command requires the persistent daemon. See Annotated Screenshots Reference for its single-image output contract and target restrictions.

12. Legacy Take Screenshot

Take a direct screenshot of the current page using the pre-Agent-Lynx command.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --fullscreen: (Optional) Capture the screenshot in fullscreen mode. Defaults to lynxview mode if not provided.
• -o, --output <path>: (Optional) Output file path.

13. Take Content Screenshot

Capture the full scrollable content of the first node matching a CSS selector.

• --selector <selector>: CSS selector for a scroll-view or compatible list. Required.
• --format <jpeg|png>: (Optional) Image format. Defaults to jpeg.
• --scale <number>: (Optional) Positive output scale. Defaults to 1.
• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• -o, --output <path>: (Optional) Output file path.

takeContentScreenshot is officially defined for scroll-view. The command accepts any CSS selector so runtimes that expose the same method on list can also be used; unsupported nodes return the UI Method failure.

See Take Content Screenshot Reference for behavior and examples.

14. Global Switch

Manage DevTool global switches.

• -c, --client <clientId>: (Optional) Client ID.

global-switch list options:

• --fail-fast: Abort on first key-read failure.

global-switch get options:

• --key <globalKey>: Global switch key. (Required)

global-switch set options:

• --key <globalKey>: Global switch key. (Required)
• --status <on|off>: Target switch status. (Required)

For the full key list and examples, see Global Switch Reference.

15. Take Heap Snapshot

Capture a QuickJS heap snapshot from the current Lynx session and save it as a .heapsnapshot file.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --thread <thread>: (Optional) Target VM thread, background or main. Defaults to background.
• -o, --output <path>: (Optional) Output file path. Defaults to the OS temp directory.

16. Query Global Memory Usage

Query Lynx global memory usage through the global Memory.* CDP domain. Use the generic cdp command and send the request to the global DevTool handler with session ID -1.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: CDP session ID. Use -1 for the global DevTool handler unless you have a platform-specific reason to override it.
• params.timeoutMs (Optional): Non-negative timeout in milliseconds. Maximum value is 300000.

The command prints the raw Memory.getAllMemoryUsage JSON. Do not expect the CLI output to contain derived summary, topMemoryItems, or topInstances wrapper fields.

When the DevTool MCP server is available, prefer the Memory_getAllMemoryUsage MCP tool for the same raw payload instead of shelling out to the CLI.

Agent-side reporting standard:

1. Save the complete raw JSON to a file when the user asks for a capture or when the result is too large to show inline.
2. Use binary units (KiB, MiB, GiB) with two decimal places. Render ratioToApp and contribution ratios as percentages with two decimal places.
3. Report this fixed summary first:
   • collectionStatus
   • ${completedInstanceCount}/${expectedInstanceCount} Lynx instances
   • totalBytes
   • appBytes
   • ratioToApp
   • elementNodeCount
   • viewBytes
   • mainThreadRuntimeBytes
   • backgroundThreadRuntimeBytes
4. Then report "Top 5 Memory Contributors" using fine-grained candidate items from each instances[] entry:
   • instances[i].backgroundThreadRuntimeBytes
   • instances[i].mainThreadRuntimeBytes
   • instances[i].elementBytes
   • each instances[i].viewDetail[category].sizeBytes
   • if instances[i].viewBytes is larger than the sum of viewDetail[*].sizeBytes, include an other view memory item for the remainder.
5. Sort the Top 5 contributors by bytes descending. For each row include rank, item kind/category, size, % of totalBytes, % of instance.totalBytes, instanceId, and URL.
6. Then report "Instances" sorted by instance.totalBytes descending. For each instance include instanceId, URL, totalBytes, mainThreadRuntimeBytes, backgroundThreadRuntimeBytes, viewBytes, elementBytes, and a compact viewDetail summary such as image=12 / 4.15 MiB.
7. Do not invent missing fields. If viewDetail is empty or a category has 0 bytes, say so plainly. The current CDP payload does not expose a nested child LynxView object tree.

Memory.getAllMemoryUsage is different from Runtime.getHeapUsage: it returns a global Lynx-attributed memory snapshot across live registered Lynx instances, including element, view, main-thread runtime, background runtime, app footprint, and per-instance breakdowns. The current CDP payload does not expose a separate nested child LynxView memory tree; viewDetail is aggregated by UI view category or tag. For the full response shape, see Memory CDP Methods.

17. Recording

Record Lynx page interactions via TestBench (CDP-based). Captures all actions (template loads, touch events, JS module calls, data updates) and produces a JSON replay file.

• -c, --client <clientId>: (Optional) Client ID for start and end.
• -o, --output <path>: (Optional) Output file or directory path for end. Defaults to ~/.lynx-devtool/files/lynxrecorder/recording-<clientId>-<timestamp>.json.

Workflow:

1. Run recorder start. If it enables enable_debug_mode, restart the app and run recorder start again.
2. User opens and interacts with the Lynx page.
3. Run recorder end --output <file.json> to stop and save.
4. Report the absolute file path to the user.

Important: For a replayable file, open or reload the target page after recorder start so the recording includes loadTemplate.

See Recording Reference for more details.

18. Performance Trace Recording

Record a compressed Lynx performance trace and save it as a .pftrace file. Start tracing before building or opening the target page so the capture includes its first frame.

• -c, --client <clientId>: (Optional) Client ID. If several clients are connected, list them and select one explicitly.
• trace start --no-systrace: Disable systrace; it is enabled by default.
• trace start --include-categories <categories> / --exclude-categories <categories>: Include or exclude comma-separated trace categories.
• trace start --enable-memory-trace: Enable memory data collection.
• trace start --no-force-gc: Disable automatic garbage collection, which is enabled by default.
• trace start --enable-auto-heap-snapshot: Capture automatic heap snapshots for shared-group VMs. Add --shared-group-id <id> to select one VM.
• trace start --js-profile-interval <interval>: JS sampling interval. Defaults to 100 when profiling is enabled and the supplied interval is 0 or -1; otherwise it defaults to -1.
• trace start --js-profile-type <quickjs|v8>: Enable profiling for the selected JS runtime. Profiling is disabled when this option is omitted.
• trace end --timeout <seconds>: Time to wait for Tracing.tracingComplete. Defaults to 30.
• trace read-data --stream <handle>: Numeric stream handle returned by trace end.
• trace read-data -o, --output <path>: Output path. Defaults to a timestamped .pftrace in the OS temporary directory.
• trace read-data --timeout <seconds>: Total download timeout. Defaults to 30.
• trace event-summary <trace>: Print every Perfetto slice.name and its occurrence count, sorted by count descending. Add --json for structured evidence and -o, --output <path> to write it to a file.
• trace query <trace> --sql <query>: Run inline Perfetto SQL and emit JSON.
• trace query <trace> --sql-file <path>: Run SQL from a file. Use exactly one of --sql and --sql-file; --max-rows defaults to 1000.

trace query and trace event-summary are local, offline commands. They do not connect to a device, start the daemon, or create a connector transport. Their JSON includes the trace's absolute path, byte length, and SHA-256 so an agent can prove which file it inspected. SQL bigint values are decimal strings and blobs are { "base64": "..." } objects.

On Android, the first trace start may enable enable_debug_mode and ask for an app restart. Restart the app and run trace start again before opening the page. A runtime without trace support requires an Android local_test build or an iOS Lynx Profile build. See Performance Trace Reference for the complete workflow and troubleshooting.

19. ReactLynx Component Tree

Print the component tree of a running ReactLynx page, decoded from @lynx-js/preact-devtools. The CLI calls the connector daemon's ReactLynx ActionCore; the daemon owns the Lynx.onVMEvent stream, the init+refresh handshake, operation_v2 decoding, and the per-session component cache. The CLI only renders the returned tree.

• -c, --client <clientId>: (Optional) Client ID.
• -s, --session <sessionId>: (Optional) Session ID.
• --depth <n>: (Optional) Maximum tree depth to print. Default: unbounded.
• --show-shells: Include the synthetic Fragment / Root / Anonymous wrappers ReactLynx inserts. They are hidden by default.
• --json: Emit { labels, roots, nodes } instead of ASCII; use this when a script will consume the tree.

Output uses @cN [type] Name references (the convention from agent-react-devtools). Labels are pre-order DFS over visible roots. reactlynx tree always captures a fresh generation and caches the exact label view it emitted, including --depth; later component @cN and update-* @cN calls reuse that view across independent CLI invocations. Compact and --show-shells label views are cached separately.

Requirements:

• ReactLynx commands require the connector daemon; do not combine them with --no-daemon.
• The page must be a dev build running @lynx-js/preact-devtools (production bundles strip setupReactLynx()). Successful initialization logs [PREACT DEVTOOLS] Devtools initialized successfully to the device console.
• @lynx-js/preact-devtools must include the document.body and preactDevtoolsCtx.Node fixes (PR #2 + PR #5 against lynx-family/preact-devtools). Without them, the refresh channel will return zero operation_v2 frames and the CLI will print the "stale preact-devtools" diagnostic.

When the tree comes back empty, the CLI exits with code 1 and writes one of three targeted diagnostics on stderr:

• saw 0 frames: nothing replied on the PreactDevtools channel. The App is most likely missing @lynx-js/preact-devtools, is a production build, has not finished setupReactLynx(), or you picked the wrong --session.
• saw N frames but no operation_v2: the hook is loaded but its refresh handler is buggy. Upgrade @lynx-js/preact-devtools to a build that contains PRs #2 and #5.
• tree is empty: every node was unmounted between commits -- rare, rerun with DEBUG (below) to see the raw envelopes.

For deep debugging, set DEBUG=devtool-mcp-server:reactlynx to log every PreactDevtools frame (type + payload size) on stderr while leaving stdout (the tree / JSON) clean:

20. ReactLynx Component Inspect

Inspect a single ReactLynx component (props / state / hooks / context / signals) by sending the Preact DevTools inspect envelope and reading back inspect-result.

• <ref>: either a label @cN produced by reactlynx tree / reactlynx find, or a numeric vnode id.
  • With @cN, the daemon resolves the label against its latest matching label view. On a cache miss it captures a tree once. Pass --show-shells if (and only if) the label was generated with shells visible.
  • With a numeric id (e.g. 3856353762), the component cache is bypassed.
• -c, --client <clientId>, -s, --session <sessionId>: (Optional) standard targeting flags.
• --show-shells: When resolving @cN, count synthetic Fragment / Root / Anonymous wrappers the same way reactlynx tree --show-shells does.
• --refresh: Capture a new full tree before resolving @cN. It has no effect on numeric ids.
• --json: Print the raw InspectData payload as JSON. Default output is a compact ASCII summary.

Example output:

Complex values are tagged by upstream's serialize.ts -- { "type": "function", "name": "..." }, { "type": "vnode", "name": "..." }, { "type": "signal", "value": ... }, { "type": "map", "entries": [...] }, etc. See serialize.ts for the full schema.

If the App fails to reply with an inspect-result, the daemon evicts that session's ReactLynx cache and the CLI exits with code 1. Run reactlynx tree before retrying. The same DEBUG=devtool-mcp-server:reactlynx namespace traces every frame.

21. ReactLynx Component Find

Find every component whose name matches a substring or regex. Output is ordered identically to reactlynx tree (pre-order DFS) so the @cN labels round-trip with the other subcommands.

• <pattern>: substring (default, case-insensitive) or JavaScript regex with --regex.
• -c, --client <clientId>, -s, --session <sessionId>: (Optional) standard targeting flags.
• --regex: Treat <pattern> as a JavaScript regular expression (e.g. --regex '^Toast(List)?$').
• --show-shells: Include synthetic Fragment / Root / Anonymous wrappers.
• --refresh: Capture a new component generation before searching. Without it, find reuses the daemon cache (and captures once on a cache miss).
• --limit <n>: Maximum number of matches to print. Default 50.
• --json: Emit [{ label, id, name, type, key, ancestors: [{label, name}] }, ...] for scripted post-processing.

Example output:

reactlynx find is the recommended way to discover labels for follow-up reactlynx component @cN calls when the tree is too large to scan visually. A successful find publishes its full-depth label view as the latest view for the selected shell mode.

22. ReactLynx Element/Component Link

Resolve one exact relationship between the latest daemon-cached DOM Snapshot and the daemon-cached ReactLynx component tree:

The command also accepts a numeric Preact VNode id in place of @cN and supports --json, --show-shells, and --refresh. By default it reuses the latest component generation and exact label view for the selected shell mode; on a component-cache miss it captures one generation. --refresh explicitly replaces the component generation before resolving the relationship.

This is an exact identity lookup through Lynx nodeId / ReactLynx uniqueId; it never falls back to coordinates, text, or tree-position matching. It uses the existing App-side element-picked and highlight protocol, so the App must contain a compatible @lynx-js/preact-devtools dev build. JSON returns the complete Snapshot ref, component label/id/type/name/key, and component cache generation.

The command deliberately does not refresh the DOM Snapshot: refreshing would silently invalidate the @eN refs the user is trying to relate. Run agent-lynx snapshot first, and rerun it explicitly when the daemon reports a missing or stale ref. Component-to-element lookup returns the first host element exposed by Preact DevTools; element-to-component lookup returns its nearest surfaced component. These directions are therefore not guaranteed to form a bijection for components that render multiple host elements.

23. ReactLynx Component Update

Mutate one field and wait for the app-side adapter's post-update inspect-result confirmation:

• <ref> follows the same cached @cN or numeric vnode-id rules as reactlynx component.
• <path> starts at the selected props/state/context object, such as count, user.name, or items.0.title. Do not prefix it with root., props., state., or context..
• <value> is parsed as JSON. Quote string JSON for the shell, or pass --raw to send the argument verbatim as a string.
• --show-shells selects the shell-inclusive label view; --refresh captures a new tree before resolving @cN.
• --json emits the raw post-update InspectData confirmation.

The daemon serializes ReactLynx operations for the same client/session so broadcast Preact VM events cannot cross-talk between concurrent commands. Different sessions can proceed in parallel. The cache is generation-based rather than a live subscription: tree and explicit --refresh replace it, find reuses it by default, and a failed cached inspect/update evicts it.