chrome-devtools-real

name	chrome-devtools-real
description	Attach Codex to the user's real Chrome profile through the `chrome-devtools-real` MCP tool. Use when the task must reuse an existing logged-in browser, extension state, multiple real tabs, or the user's normal browsing session instead of an isolated automation browser.

Chrome DevTools Real

Use this skill when Codex should operate the user's existing Chrome session instead of a fresh automation profile.

Read references/real-chrome-workflow.md when you need the detailed operating checklist, verification pattern, or fallback rules.

Core Goal

Use chrome-devtools-real to inspect and control pages that are already open in the user's real Chrome profile.

Prefer this skill when:

• the user is already logged in on the target site
• browser extensions matter
• multiple tabs or windows matter
• the site behaves differently in a clean automation profile
• the user explicitly asks for their real Chrome session

Prefer ordinary chrome-devtools when:

• the user wants an isolated session
• no real Chrome attachment is available
• the task does not depend on real profile state

Escalate from this skill to page-agent-browser when:

• direct click, fill, press_key, or small evaluate_script steps become brittle
• the task requires too many low-level steps to express cleanly
• selectors are hard to maintain or expensive to rediscover
• the flow spans multiple tabs or cross-page coordination
• GitHub or another CSP-heavy site makes normal page injection awkward
• the user explicitly asks for PageAgent or natural-language browser control
• repeated retries suggest raw browser primitives are no longer the lowest-cost path

Workflow

1. Confirm the operating context

• Assume the goal is to attach to an existing Chrome window, not to launch a brand new profile.
• Prefer the currently active tab unless the user names a different page or window.
• Treat cookies, saved sessions, and extensions as part of the working state.

2. Inspect before acting

• List pages and select the intended target page before clicking or typing.
• Take a page snapshot before major actions.
• Use direct DOM checks or page URL checks to confirm you are on the correct tab.

3. Execute deterministic browser actions

• Prefer ordinary browser primitives first: click, fill, press keys, evaluate small scripts, and verify results.
• Break multi-step work into checkpoints instead of attempting one large opaque action.
• After each meaningful step, inspect the DOM again instead of assuming the page changed as expected.

3.5. Switch to PageAgent when cost exceeds benefit

Stay in chrome-devtools-real for short, deterministic work.

Switch to page-agent-browser when the browser work is still feasible but the manual MCP path is no longer efficient or reliable.

Use this rule of thumb:

• stay here for one-step or few-step deterministic actions
• switch after repeated selector friction, repeated retries, or obvious multi-page complexity
• switch immediately on GitHub-like CSP-heavy sites when Page Agent Ext is available and the task is more than trivial

When switching:

1. Keep the current real Chrome tab selected.
2. Preserve the current browser profile and tab context.
3. Hand off the current URL, intended end state, and required final focused tab.
4. Return to this skill's verification pattern after PageAgent acts.

4. Keep tab state explicit

• For multi-tab work, record which tab should remain focused at the end.
• After navigation or tab creation, verify the selected page and URL.
• If the wrong tab ends up focused, correct it manually before reporting success.

5. Escalate only when needed

• Ask before interacting with login, payment, destructive admin, or privacy-sensitive flows.
• Avoid autonomous actions on pages containing secrets unless the user clearly requested it.

Verification Rules

• Verify page identity with URL, title, or visible snapshot content.
• Verify action results from the DOM, not from assumptions.
• Report partial success precisely when the page changed only part of the way.
• Treat wrong-tab completion as incomplete until the intended tab state is restored.

Failure Handling

• If chrome-devtools-real is unavailable, fall back to chrome-devtools only after stating that profile state may differ.
• If the target page is present in a different tab, switch to it instead of recreating the state manually.
• If an extension-dependent workflow cannot be reproduced in isolated Chrome, keep the task in the real browser path.
• If browser state appears unstable, re-list pages and reselect the target before continuing.

Integration Guidance

Translate user requests into concrete browser steps:

1. Attach to the real browser page list.
2. Identify the target tab or window.
3. Snapshot the current state.
4. Perform one deterministic action block.
5. Snapshot and verify again.
6. Restore the intended final tab state if needed.

Keep this skill focused on reliable real-browser transport.

Treat page-agent-browser as the preferred escalation path when raw browser primitives become too costly, too brittle, or too verbose.