How to use DevCDP effectively: the observe/act division of labour, the fastest path from a bug report to an exact line, and the traps worth knowing. Call it once at the start of a debugging session.

Attach to a Chrome tab over the DevTools Protocol and start observing it (console, network, DOM, debugger). Claims the tab so no other DevCDP session can drive it, marks it visibly in the browser, and reports what was loaded before we attached. Call this once at the start of a debugging session.

Connection health and buffer accounting: which tab is attached, how many console/network/script entries are held, whether the debugger is paused, and whether anything has been evicted from the buffers.

Detach cleanly: resume the page if it is paused at a breakpoint, remove every breakpoint we set, remove the in-page badge, and release the tab claim so another session can use it. Always call this when you are done.

List the debuggable tabs in Chrome with their index, title, URL, whether each is the visible one, and which DevCDP session (if any) currently owns it. Use the index with target:'index:' in devtools_connect.

Show every DevCDP session currently running on this machine and the tabs each one holds. Use it to understand why a tab is unavailable, or to confirm two agents are not fighting over the same page.

Navigate the attached tab to a URL. Returns as soon as the navigation is committed, not when loading finishes — wait for a specific request with network_wait_for_request, or for text with Playwright, before asserting.

Abort the JavaScript the page is currently running. Use it when a tool reports PAGE_UNRESPONSIVE — an infinite loop or a long synchronous task has blocked the main thread. This is the only thing that frees it: reloading and navigating do not, because the blocked thread never processes them. The page keeps its DOM and state; only the in-flight script is killed.

Reload the attached tab. Useful right after attaching, because console history and network traffic from before the attach cannot be recovered — a reload replays everything with DevCDP watching.

Read console output captured since attach: logs, warnings, uncaught exceptions with file, line and stack. Pass cursor=nextCursor from a previous call to get only what is new. Note that Chrome does not replay messages logged before DevCDP attached — reproduce the action or call page_reload to see those.

Run a JavaScript expression in the page and return its value. On failure returns the full exception detail (message, 1-based line and column, URL, stack). Use it to read app state; use debugger_evaluate_at_frame instead when you are paused and need a local variable.

Evaluate several named expressions in one round trip and get a map of name to result. Use it to sample a lot of app state at once instead of paying a round trip per question. Individual failures are reported per entry rather than aborting the batch.

Empty the console buffer so that what you read next belongs only to the action you are about to take. Does not touch the browser's own console display.

List HTTP requests captured since attach, with method, status, duration, size and initiator. Filter by URL substring, method, status or failures only. Response bodies are opt-in via include_bodies because they are large. Capture starts when DevCDP attaches, so requests from before that are not here — reload to see them.

Block until a request whose URL contains url_filter completes, then return it. Event driven, so there is no polling. Call this immediately AFTER triggering the action, or pass a filter that has not fired yet — a request that already completed is returned straight away. Gives up after timeout_ms and tells you so.

Fetch the full response body for one requestId from network_get_requests. Chrome discards bodies when the page navigates, so read them while the page is still on the same document.

Empty the network buffer so the next thing you read belongs only to the action you are about to take. Does not affect the browser's own Network panel.

Query elements by CSS selector and return tag, id, classes, text, attributes, geometry and real visibility. Ask for computed styles by naming the properties you want. Set frame:'all' to search inside iframes too — single-page apps often render the screen you care about in a child frame.

List the frames and JavaScript execution contexts in the attached tab. Use it when a selector finds nothing — the content may live in an iframe, which needs frame:'all' on dom_query.

Get the inner or outer HTML of the first element matching a selector, truncated to a byte budget. Useful for understanding structure you cannot infer from dom_query alone.

DOM changes recorded since the last call — what was added, removed or re-attributed, and where. Use it after an action to see whether the app re-rendered at all, which distinguishes 'handler never ran' from 'handler ran and produced nothing'.

Detect modal dialogs, alerts and confirmation overlays that are visible right now, with their title, message and button labels. Detection is structural — ARIA roles, the dialog element, and stacked-overlay geometry — so it works regardless of which UI framework drew it. Call it after any action that might raise a prompt.

Click an element, identified by CSS selector, visible text or test id. Waits until it is actually clickable — rendered, enabled, stopped moving, and not covered by anything — then dispatches real (trusted) mouse events, and reports what the click caused: requests fired, console errors, whether the DOM changed at all. If it never became clickable it says which of those conditions failed and what was in the way.

Move the pointer over an element and leave it there. Use before clicking anything that only appears on hover — dropdown menus, row action buttons, tooltips — because those elements do not exist to click until something is hovering over their parent.

Drag one element onto another — reordering rows, moving a card between columns, resizing a split. Dispatches a real press, several intermediate moves and a release, because drag implementations almost always ignore a press followed immediately by a release somewhere else.

Scroll the page, or scroll a specific container. Needed before interacting with anything in a virtualised list or grid, where rows outside the viewport do not exist in the DOM at all — scrolling is what creates them.

Press a key — Enter to submit, Tab to move on, Escape to dismiss, arrows to move through a list or grid. Optionally focuses an element first. This is the tool for keyboard-driven screens, where clicking the control is not how the application expects to be used.

Set the value of a text field, textarea or contenteditable in one step, and fire the input and change events the application listens for. Fast, because it does not type character by character — use ui_type instead when the field reacts to each keystroke, such as a typeahead or an autocomplete.

Type into a field one character at a time, with real key events for each. Slower than ui_fill and necessary exactly when the field reacts per keystroke — search-as-you-type, autocomplete, input masks, and fields that reformat while you type. If ui_fill left the field looking right but the application unaware, use this.

Choose an option in a dropdown, by visible label or by value. Handles a native directly; for the custom dropdowns most applications actually use — a div that opens a list — it opens the control and clicks the matching option. Reports the options it could see when nothing matches, which is usually the whole answer.

Set a checkbox or radio to a specific state, rather than toggling it blindly. Reads the current state first and clicks only if it differs, so calling it twice does not undo the first call — the usual way a 'toggle' helper leaves a form in the wrong state.

Attach one or more local files to a file input, without opening the operating system's file picker — which automation cannot drive at all. Give the absolute paths of files on the machine running Chrome.

Block until the page reaches a state: an element appears, disappears, becomes enabled, or some text shows up. This is the honest alternative to guessing a sleep — it returns as soon as the condition holds, and when it does not, it says what the page looked like instead of just timing out.

List what can be interacted with on the current screen — buttons, links, inputs, selects and anything with an interactive ARIA role — with the target you would use to reach each one. Use it when a selector fails and you need to see what is really there. Far cheaper than dumping the DOM, and it names elements the way these tools expect them to be named.

List the JavaScript files loaded in the page, with size and whether each has a source map. This is indexed the moment DevCDP attaches, so it works on a page that was already open. Filter by URL substring to find the file you need before setting a breakpoint.

Search the text of every loaded script — and every original file recoverable from source maps — for a string or regular expression. This is the fastest way to locate a handler when you know a function name, a message or a field name but not the file. Returns file, 1-based line and the matching line.

Read the source Chrome actually loaded, by scriptId or URL substring, optionally a line range. Lines come back numbered so the numbers you quote to a breakpoint are the numbers you saw.

List the original source files recoverable from the page's source maps — the pre-bundling file tree. Use it to discover real file paths before calling source_get_file or setting a breakpoint on an original file.

Read an original pre-bundling source file via the page's source maps. Falls back to the loaded script when no map is available, and always tells you which of the two you got, so a bundle line is never mistaken for an original one.

Set a breakpoint and report honestly whether Chrome could bind it. Accepts either a loaded script URL (a substring is resolved to the exact script) or an original pre-bundling file path, which is translated through the source map. Set auto_resume:true when the action is being driven by an automation tool, so the page does not stay frozen and time that action out.

Set a breakpoint on a function you can name, without knowing which file it lives in. Give any expression that evaluates to a function — 'app.saveOrder', 'MyClass.prototype.load', a framework helper — and DevCDP finds its definition and breaks at its first statement. Use this when you know what runs but not where it is defined; use debugger_set_breakpoint when you already have a file and line.

List the breakpoints DevCDP has set, including whether each is actually bound to executable code. An unbound breakpoint will never fire — check here first when a breakpoint 'is not hitting'.

Remove one breakpoint by its breakpointId. Use debugger_remove_all_breakpoints to clear them in one call.

Remove every breakpoint DevCDP set, and resume the page if it is currently paused. Call this before handing the browser back to a human, so they do not find a frozen app.

Pause JavaScript execution at the next statement the page runs, and hold it so you can inspect and step. The page is frozen while held, so DevCDP releases it automatically after maxPauseMs if you have not resumed — no human ever has to press resume in Chrome.

Resume execution and drop any hold. Breakpoints resume themselves by default, so this is only needed after an explicit pause, after stepping, or after a breakpoint set with auto_resume:false.

Step over from the current pause and stop at the next statement. Stepping implies you want the pause held, so it will not auto-resume between steps — but it is still released automatically after maxPauseMs if you stop. The new location and scope are available from debugger_get_state and debugger_get_scope once it settles.

Step into from the current pause and stop at the next statement. Stepping implies you want the pause held, so it will not auto-resume between steps — but it is still released automatically after maxPauseMs if you stop. The new location and scope are available from debugger_get_state and debugger_get_scope once it settles.

Step out from the current pause and stop at the next statement. Stepping implies you want the pause held, so it will not auto-resume between steps — but it is still released automatically after maxPauseMs if you stop. The new location and scope are available from debugger_get_state and debugger_get_scope once it settles.

Where execution is paused right now: the reason, and the full call stack with function names and 1-based file positions. Returns paused:false when the page is running.

Read the variables in scope at a paused call frame, with objects and arrays expanded rather than printed as 'Object'. Includes this. Anything omitted for size is explicitly marked, so you never have to guess whether you saw the whole value.

Evaluate an expression in the scope of a paused call frame, so local variables and closures are in scope. This is how you confirm a hypothesis with a real value rather than inferring one.

Everything captured automatically at the last breakpoint hit — scope for the top frames, recent console output and recent network requests — in one call instead of four. Tells you whether the pause is still current or has already resumed, so a stale snapshot is never mistaken for live state.

Show a short status line to the human, in the badge on the page you are debugging. This is the only channel the user actually sees — call it before a slow or surprising step so a frozen-looking app is explained. Keep it to a few words.

Open a debugging session with a goal and an ordered list of steps, so progress is tracked and a failed step can fall back to asking the human. Use it for multi-step reproductions; a single-question investigation does not need it.

Mark the current step complete with what you found, and advance. Returns the next step, or allDone when the plan is finished.

Report that you cannot complete the current step yourself. Checks memory for a known recovery first, then tells you how to hand over to the human. Use it for anything automation genuinely cannot do — a login you have no credentials for, a challenge, a physical device.

Ask the human to do something in the browser, and show the request in the on-page badge with a confirmation button. Returns immediately — poll session_poll_user_action for the outcome. Also relay the instruction in your reply, so it is visible whether or not they are looking at the browser window.

Check whether the human has completed what session_ask_user requested. Returns acted:false while waiting. Poll at a human pace — a few seconds apart — rather than in a tight loop.

What the human has done in the browser — clicks, typed values, chosen options, submissions — and the element each one touched. Works whether or not you asked, so unprompted help is still readable. Pass the cursor back for only what is new. Values are captured during a handover or takeover; sensitive fields stay redacted.

Unified timeline of everything observed in this session — console output, requests, navigations, dialogs, clicks, pauses and handovers, in order. Use it to reconstruct what happened when a step behaved unexpectedly.

Where the session plan stands: the goal, each step's status, which step is current, and whether a human handover is outstanding.

Close the session and return a summary. Does not detach — call devtools_disconnect to release the tab and clear breakpoints when you are finished with the browser entirely.

One snapshot of console output, network requests and DOM mutations together, instead of three separate calls. Pass the cursors back on the next call to get only what is new. This is the cheapest way to see the effect of an action.

Look up what previous sessions learned about this app — failures and the recovery that worked. Returns short summaries so it is cheap to call at the start of a session; pass full:true or an id to read one in detail. Search it whenever a step fails, before asking the user for help.

Record a failure and the recovery that worked, so a later session can skip the dead end. Call it after any user-assisted recovery or non-obvious workaround. All four fields are required and validated — a vague entry is worse than none, because it costs context on every future lookup.

One-off import of a v4 Markdown memory file into the current store, skipping the malformed entries v4's missing validation produced. Run once after upgrading, then delete the old file.

Ask the running page what it is: which UI libraries it uses, how it routes, how many frames it has, and its actual interactive surface — visible buttons, fields, grids and tabs with working selectors. Call this once before driving an unfamiliar app, instead of guessing selectors.

Build a map of the backend the page actually talks to: endpoints grouped with ids collapsed, call counts, status codes, timings and failures — plus an OpenAPI/Swagger specification if the server publishes one at a standard path. Use it to understand the API surface, and to see at a glance which calls are failing.

Search the project's own documentation — README and any markdown/text/pdf docs under the configured docs root — and return matching passages with file and line. Use it to learn what a screen, field or business term means in this app, instead of inferring it from the UI. Set docsRoot in your settings file if the docs live elsewhere.

List the documentation available under the docs root, with each file's headings, so you can see what the project documents before searching. A good first call when you do not yet know the app's vocabulary.

Show every DevCDP setting: its effective value, where that value came from (default, which settings file, or which environment variable), which files were searched and loaded, and any that failed to parse or were not recognised. Use it before changing configuration, and to check a change actually took effect.

Write a settings file containing every option with its current value and an explanation, so it can be edited by hand. Refuses to overwrite an existing file unless you say so.