Cdp layer

.gitignore

@@ -7,7 +7,7 @@ yarn-error.log*
 lerna-debug.log*
 .pnpm-debug.log*
 tmp
-debug
+/debug
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

README.md

@@ -136,7 +136,7 @@ await page.aiAction("click the login button");
 **Best for**: Complex workflows requiring multiple steps and visual context
 
 **Advantages**:
-- 🖼️ **Visual Understanding** - Uses screenshots with element overlays
+- 🖼️ **Visual Understanding** - Can use screenshots with element overlays
 - 🎭 **Complex Tasks** - Handles multi-step workflows automatically
 - 🧠 **Context-Aware** - Better at understanding page layout and relationships
 - 🔄 **Adaptive** - Can adjust strategy based on page state
@@ -370,6 +370,16 @@ const agent = new HyperAgent({
 });
 ```
 
+## CDP First
+
+HyperAgent speaks Chrome DevTools Protocol natively. Element lookup, scrolling, typing, frame management, and screenshots all go through CDP so every action has exact coordinates, execution contexts, and browser events. This allows for more custom commands and deep iframe tracking.
+
+HyperAgent integrates seamlessly with Playwright, so you can still use familiar commands, while the actions take full advantage of native CDP protocol with fast locators and advanced iframe tracking.
+
+Keep in mind that CDP is still experimental, and stability is not guaranteed. If you’d like the agent to use Playwright’s native locators/actions instead, set `cdpActions: false` when you create the agent and it will fall back automatically.
+
+The CDP layer is still evolving—expect rapid polish (and the occasional sharp edge). If you hit something quirky you can toggle CDP off for that workflow and drop us a bug report.
+
 ## Contributing
 
 We welcome contributions to Hyperagent! Here's how you can help:

package.json

@@ -58,7 +58,9 @@
     "playwright-core": "^1.56.1",
     "readline": "^1.3.0",
     "turndown": "^7.2.0",
-    "zod": "^4.1.8"
+    "zod": "^4.1.8",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/lodash": "^4.17.16",