chrome-cdp-cli 1.2.2 → 1.2.4

package/README.md

@@ -1,6 +1,44 @@
 # Chrome DevTools CLI
 
-A powerful command-line tool for controlling Chrome browser instances via the Chrome DevTools Protocol (CDP). This tool provides programmatic access to browser automation, debugging, and inspection capabilities without requiring a graphical interface.
+**Built for LLMs - Eval-First Browser Automation**
+
+A command-line tool designed specifically for Large Language Models (LLMs) and AI-assisted development. Controls Chrome browser via Chrome DevTools Protocol (CDP) with an **eval-first design philosophy** - most automation tasks use JavaScript execution because LLMs excel at writing and validating scripts quickly.
+
+**Why eval-first?** LLMs are exceptional at writing JavaScript. This tool leverages that strength by using `eval` for most operations, enabling AI assistants (Claude, Cursor, etc.) to write automation scripts instantly and test them in real-time. Includes built-in IDE integrations: install Cursor commands and Claude skills directly.
+
+## 🚀 Built for LLMs - Eval-First Design Philosophy
+
+**This tool is specifically designed for Large Language Models (LLMs) and AI-assisted development.**
+
+### Why Most Commands Use Eval
+
+**The core design principle:** Most browser automation tasks are accomplished through the `eval` command rather than dedicated CLI commands. This is intentional and optimized for LLM workflows:
+
+1. **🧠 LLMs Excel at JavaScript**: Large Language Models are exceptionally good at writing JavaScript code. They can generate complex automation scripts, handle async operations, and adapt to different scenarios - all in JavaScript.
+
+2. **⚡ Rapid Script Validation**: LLMs can write a script, test it immediately with `eval`, see the results, and refine it in seconds. This iterative loop is where LLMs shine.
+
+3. **🔄 Maximum Flexibility**: Instead of waiting for specific commands to be implemented, LLMs can accomplish any browser task through JavaScript execution. Need to click an element? `document.querySelector('#btn').click()`. Need to wait for content? `await new Promise(...)`. Need complex data extraction? Just write the JavaScript.
+
+4. **🎯 Perfect for AI Workflows**: When you ask Claude or Cursor to automate a browser task, they can write the JavaScript directly - no need to learn complex CLI syntax or wait for feature implementations.
+
+### IDE Integration for LLM Workflows
+
+**Built-in support for AI development environments:**
+
+- **🖥️ Cursor Commands**: Install with `install-cursor-command` - brings browser automation directly into Cursor's command palette
+- **🤖 Claude Skills**: Install with `install-claude-skill` - enables Claude to use browser automation in conversations
+- **⚡ Seamless Integration**: AI assistants can generate automation scripts and execute them instantly through these integrations
+
+**Why this matters:** When LLMs are integrated into your IDE, they can write browser automation scripts as part of your development workflow. The eval-first approach means they can accomplish any task without waiting for specific command implementations.
+
+### The LLM Advantage
+
+- **🧠 Natural Language → JavaScript**: Ask an LLM "click the submit button" → it generates `document.querySelector('#submit').click()`
+- **⚡ Instant Testing**: Write, execute, see results, refine - all in seconds
+- **🔄 Iterative Refinement**: LLMs can adjust scripts based on results immediately
+- **📚 Context-Aware**: AI understands your project and can write automation scripts that fit your specific needs
+- **🎯 No Learning Curve**: LLMs already know JavaScript - no need to learn CLI-specific syntax
 
 ## Implementation Status
 
@@ -15,9 +53,9 @@ A powerful command-line tool for controlling Chrome browser instances via the Ch
 - 🛠️ **IDE Integration**: Install Cursor commands and Claude skills with directory validation and --force option
 - 📦 **Build System**: Complete TypeScript build pipeline with testing framework
 
-### 🚧 Eval Workaround Available
+### 🚧 Eval-First Design - LLM-Optimized Features
 
-These features are not directly implemented but can be achieved using the `eval` command:
+These features use the `eval` command by design (not as workarounds) - this is the intended approach for LLM-assisted development:
 
 - 📄 **Page Navigation**: `eval "window.location.href = 'https://example.com'"`
 - 🖱️ **Element Interaction**: `eval "document.querySelector('#btn').click()"`
@@ -27,6 +65,31 @@ These features are not directly implemented but can be achieved using the `eval`
 - 📱 **User Agent**: `eval "navigator.userAgent"`
 - 🌐 **Network Requests**: `eval "fetch('/api').then(r => r.json())"`
 
+**Why this design is optimal for LLMs:**
+
+1. **LLMs are JavaScript experts**: They can write complex automation scripts instantly
+2. **Rapid validation**: Write → Execute → See Results → Refine - perfect for LLM workflows
+3. **No feature waiting**: LLMs can accomplish any task through JavaScript without waiting for CLI command implementations
+4. **Natural workflow**: When you ask an LLM to automate something, it writes JavaScript - exactly what `eval` executes
+5. **Maximum flexibility**: Any browser API, any complexity level, any scenario - all through JavaScript
+
+**This is not a limitation - it's a feature designed specifically for AI-assisted development.**
+
+### 🎯 IDE Integration - Built for LLM Workflows
+
+**Why we support Cursor Commands & Claude Skills:**
+
+This tool is designed for LLM-assisted development. The IDE integrations (`install-cursor-command` and `install-claude-skill`) bring browser automation directly into AI-powered development environments:
+
+- **🔄 Seamless LLM Workflow**: AI assistants can write and execute browser automation scripts directly in your IDE
+- **🧠 AI-Native Design**: The eval-first approach means LLMs can accomplish any browser task through JavaScript
+- **⚡ Instant Script Validation**: LLMs write JavaScript → execute via eval → see results → refine - all in real-time
+- **📚 Context-Aware Automation**: AI understands your project context and can generate relevant automation scripts
+- **🎯 Natural Language → Automation**: Ask "click the submit button" → AI generates `document.querySelector('#submit').click()` → executes instantly
+- **🤖 Perfect for AI Assistants**: Claude and Cursor can use browser automation as part of their toolset
+
+**The integration exists because this tool is built for LLMs - the eval-first design and IDE integrations work together to enable AI-powered browser automation.**
+
 ### ⏳ Not Yet Implemented
 
 - 📄 **Direct Page Management**: Native commands for creating, closing, listing, and selecting tabs
@@ -498,15 +561,25 @@ new Promise(resolve => {
    - Quiet and verbose modes
    - Custom output templates
 
-### Why Use Eval Workarounds?
+### Why Eval-First Design? (Built for LLMs)
+
+**This is not a workaround - it's the core design philosophy optimized for LLM workflows:**
+
+1. **🧠 LLMs are JavaScript Experts**: Large Language Models excel at writing JavaScript. They can generate complex automation scripts, handle async operations, and adapt to different scenarios - all naturally in JavaScript.
+
+2. **⚡ Rapid Script Validation**: The perfect workflow for LLMs: Write JavaScript → Execute via `eval` → See Results → Refine. This iterative loop is where LLMs shine.
+
+3. **🔄 Maximum Flexibility**: Any browser task, any complexity, any scenario - all through JavaScript. No waiting for specific command implementations.
+
+4. **🤖 AI-Native Workflow**: When you ask Claude or Cursor to automate something, they write JavaScript - exactly what `eval` executes. Perfect alignment.
+
+5. **📚 Natural Language → Automation**: "Click the submit button" → AI generates `document.querySelector('#submit').click()` → Executes instantly.
+
+6. **🎯 Context-Aware**: AI understands your project and can write automation scripts that fit your specific needs.
 
-The eval approach offers several advantages:
+7. **⚡ Instant Iteration**: LLMs can adjust scripts based on results immediately - no need to wait for feature releases.
 
-- **Immediate availability**: No waiting for feature implementation
-- **Maximum flexibility**: Any JavaScript operation is possible
-- **Learning opportunity**: Better understanding of browser APIs
-- **Custom solutions**: Tailor automation to specific needs
-- **Future-proof**: Works with any web technology
+**This tool is built for LLM-assisted development. The eval-first approach, combined with IDE integrations (Cursor commands & Claude skills), creates a seamless workflow where AI assistants can automate browser tasks as part of your development process.**
 
 ## Configuration
 

package/dist/cli/CommandRouter.js

@@ -87,7 +87,7 @@ class CommandRouter {
             case 'disconnect':
                 return this.executeDisconnectCommand();
             case 'install_cursor_command':
-            case 'install_claude_skill':
+            case 'install_claude_skill': {
                 const handler = this.registry.get(command.name);
                 if (!handler) {
                     return {
@@ -97,6 +97,7 @@ class CommandRouter {
                     };
                 }
                 return await handler.execute(null, command.args);
+            }
             default:
                 return {
                     success: false,
@@ -246,6 +247,10 @@ For more information about a specific command, use:
             'snapshot': 'Capture DOM snapshot with structure and styles',
             'console-messages': 'Get console messages',
             'network-requests': 'Get network requests',
+            'get_console_message': 'Get the latest console message',
+            'list_console_messages': 'List all console messages with filtering',
+            'get_network_request': 'Get the latest network request',
+            'list_network_requests': 'List all network requests with filtering',
             'install_cursor_command': 'Install Cursor IDE commands for Chrome automation',
             'install_claude_skill': 'Install Claude Code skill for Chrome automation',
             'help': 'Show help information'

package/dist/handlers/InstallClaudeSkillHandler.js

@@ -69,7 +69,7 @@ Examples:
                     }
                 }
             }
-            await this.ensureDirectory(skillDir);
+            await this.ensureSkillDirectoryPath(targetDir, skillDir);
             const skillConfig = this.generateClaudeSkill();
             const skillPath = path.join(skillDir, 'SKILL.md');
             await fs.writeFile(skillPath, this.generateSkillMarkdown(skillConfig), 'utf8');
@@ -123,6 +123,20 @@ Examples:
             logger_1.logger.info(`Created directory: ${dirPath}`);
         }
     }
+    async ensureSkillDirectoryPath(targetDir, skillDir) {
+        if (targetDir.includes('.claude/skills') || targetDir.endsWith('.claude/skills')) {
+            const claudeDir = targetDir.includes('.claude/skills')
+                ? targetDir.substring(0, targetDir.indexOf('.claude') + 7)
+                : path.dirname(targetDir);
+            await this.ensureDirectory(claudeDir);
+            const skillsDir = path.join(claudeDir, 'skills');
+            await this.ensureDirectory(skillsDir);
+            await this.ensureDirectory(skillDir);
+        }
+        else {
+            await this.ensureDirectory(skillDir);
+        }
+    }
     getDefaultSkillDirectory(skillType) {
         return skillType === 'personal'
             ? path.join(os.homedir(), '.claude', 'skills')
@@ -417,6 +431,65 @@ chrome-cdp-cli list_console_messages --type error > errors.log
 # Cleanup
 kill $CHROME_PID
 \`\`\`
+`;
+    }
+    getHelp() {
+        return `
+install-claude-skill - Install Claude Code skill for Chrome browser automation
+
+Usage:
+  install-claude-skill
+  install-claude-skill --skill-type personal
+  install-claude-skill --target-directory /path/to/.claude/skills
+  install-claude-skill --include-examples --include-references
+
+Arguments:
+  --skill-type <type>         Installation type: 'project' or 'personal' (default: project)
+  --target-directory <path>   Custom installation directory
+  --include-examples          Include examples.md file with usage examples
+  --include-references        Include reference.md file with detailed API documentation
+  --force                     Force installation without directory validation
+
+Description:
+  Installs a Claude Code skill that provides Chrome browser automation capabilities
+  within Claude IDE. The skill enables Claude to help with:
+
+  • Browser automation and testing
+  • JavaScript execution and debugging
+  • Web scraping and data extraction
+  • UI testing and interaction
+  • Performance monitoring
+
+Installation Types:
+  project  - Install in current project (.claude/skills/cdp-cli/)
+  personal - Install in user home directory (~/.claude/skills/cdp-cli/)
+
+Directory Validation:
+  For project installation, the command checks for a .claude directory to ensure
+  you're in a project root. Use --force to bypass this validation or 
+  --target-directory to specify a custom location.
+
+Examples:
+  # Install in current project (requires .claude directory)
+  install-claude-skill
+
+  # Install for personal use (in home directory)
+  install-claude-skill --skill-type personal
+
+  # Install with examples and references
+  install-claude-skill --include-examples --include-references
+
+  # Install with custom directory
+  install-claude-skill --target-directory /path/to/.claude/skills
+
+  # Force install without validation
+  install-claude-skill --force
+
+Note:
+  The installed skill leverages the eval command approach, which is particularly
+  powerful for LLM-assisted development. Claude can write and test JavaScript
+  automation scripts dynamically, making it ideal for rapid prototyping and
+  complex browser automation tasks.
 `;
     }
 }

package/dist/handlers/InstallCursorCommandHandler.js

@@ -63,7 +63,7 @@ Examples:
                     };
                 }
             }
-            await this.ensureDirectory(targetDir);
+            await this.ensureDirectoryPath(targetDir);
             const commands = this.generateCursorCommands();
             const createdFiles = [];
             for (const command of commands) {
@@ -109,6 +109,19 @@ Examples:
             logger_1.logger.info(`Created directory: ${dirPath}`);
         }
     }
+    async ensureDirectoryPath(targetPath) {
+        if (targetPath.includes('.cursor/commands') || targetPath.endsWith('.cursor/commands')) {
+            const cursorDir = targetPath.includes('.cursor/commands')
+                ? targetPath.substring(0, targetPath.indexOf('.cursor') + 7)
+                : path.dirname(targetPath);
+            await this.ensureDirectory(cursorDir);
+            const commandsDir = path.join(cursorDir, 'commands');
+            await this.ensureDirectory(commandsDir);
+        }
+        else {
+            await this.ensureDirectory(targetPath);
+        }
+    }
     generateCursorCommands() {
         return [
             {
@@ -274,6 +287,54 @@ chrome-cdp-cli snapshot --filename page-analysis.json
 # 3. 检查控制台错误
 chrome-cdp-cli list_console_messages --type error
 \`\`\`
+`;
+    }
+    getHelp() {
+        return `
+install-cursor-command - Install Cursor IDE commands for Chrome browser automation
+
+Usage:
+  install-cursor-command
+  install-cursor-command --target-directory /path/to/.cursor/commands
+  install-cursor-command --force
+
+Arguments:
+  --target-directory <path>   Custom installation directory (default: .cursor/commands)
+  --include-examples          Include example usage (default: true)
+  --force                     Force installation without directory validation
+
+Description:
+  Installs a unified Cursor command file (cdp-cli.md) that provides Chrome browser
+  automation capabilities directly within Cursor IDE. The command includes:
+
+  • JavaScript execution in browser context
+  • Screenshot capture and DOM snapshots
+  • Console and network monitoring
+  • Complete automation workflows
+  • Comprehensive examples and documentation
+
+Directory Validation:
+  By default, the command checks for a .cursor directory to ensure you're in a
+  Cursor project root. Use --force to bypass this validation or --target-directory
+  to specify a custom location.
+
+Examples:
+  # Install in current project (requires .cursor directory)
+  install-cursor-command
+
+  # Install with custom directory
+  install-cursor-command --target-directory /path/to/.cursor/commands
+
+  # Force install without validation
+  install-cursor-command --force
+
+  # After installation, use in Cursor with:
+  /cdp-cli
+
+Note:
+  The installed command provides powerful browser automation through the eval
+  approach, which is ideal for LLM-assisted development as it allows writing
+  and testing JavaScript automation scripts quickly and flexibly.
 `;
     }
 }

package/dist/handlers/TakeSnapshotHandler.js

@@ -10,59 +10,131 @@ class TakeSnapshotHandler {
     async execute(client, args) {
         const snapshotArgs = args;
         try {
-            await client.send('DOMSnapshot.enable');
             await client.send('DOM.enable');
             await client.send('CSS.enable');
-            const params = this.buildSnapshotParams(snapshotArgs);
-            const response = await client.send('DOMSnapshot.captureSnapshot', params);
-            if (!response || !response.documents || response.documents.length === 0) {
-                return {
-                    success: false,
-                    error: 'Failed to capture DOM snapshot: empty response'
-                };
+            try {
+                return await this.captureWithDOMSnapshot(client, snapshotArgs);
             }
-            const processedSnapshot = this.processSnapshot(response, snapshotArgs);
-            if (snapshotArgs.filename) {
-                await this.saveSnapshot(processedSnapshot, snapshotArgs.filename, snapshotArgs.format);
-                return {
-                    success: true,
-                    data: {
-                        message: `DOM snapshot saved to ${snapshotArgs.filename}`,
-                        filename: snapshotArgs.filename,
-                        format: snapshotArgs.format || 'json',
-                        documentsCount: response.documents.length,
-                        nodesCount: response.documents[0]?.nodes?.nodeName?.length || 0
-                    }
-                };
+            catch (domSnapshotError) {
+                return await this.captureWithDOM(client, snapshotArgs);
             }
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    async captureWithDOMSnapshot(client, snapshotArgs) {
+        await client.send('DOMSnapshot.enable');
+        const params = this.buildSnapshotParams(snapshotArgs);
+        const response = await client.send('DOMSnapshot.captureSnapshot', params);
+        if (!response || !response.documents || response.documents.length === 0) {
+            throw new Error('Failed to capture DOM snapshot: empty response');
+        }
+        const processedSnapshot = this.processSnapshot(response, snapshotArgs);
+        if (snapshotArgs.filename) {
+            await this.saveSnapshot(processedSnapshot, snapshotArgs.filename, snapshotArgs.format);
             return {
                 success: true,
                 data: {
-                    snapshot: processedSnapshot,
+                    message: `DOM snapshot saved to ${snapshotArgs.filename}`,
+                    filename: snapshotArgs.filename,
                     format: snapshotArgs.format || 'json',
                     documentsCount: response.documents.length,
                     nodesCount: response.documents[0]?.nodes?.nodeName?.length || 0
                 }
             };
         }
-        catch (error) {
+        return {
+            success: true,
+            data: {
+                snapshot: processedSnapshot,
+                format: snapshotArgs.format || 'json',
+                documentsCount: response.documents.length,
+                nodesCount: response.documents[0]?.nodes?.nodeName?.length || 0
+            }
+        };
+    }
+    async captureWithDOM(client, snapshotArgs) {
+        const docResponse = await client.send('DOM.getDocument', { depth: -1 });
+        if (!docResponse || !docResponse.root) {
+            throw new Error('Failed to get document root');
+        }
+        const htmlResponse = await client.send('DOM.getOuterHTML', {
+            nodeId: docResponse.root.nodeId
+        });
+        if (!htmlResponse || !htmlResponse.outerHTML) {
+            throw new Error('Failed to get document HTML');
+        }
+        let processedSnapshot;
+        if (snapshotArgs.format === 'html') {
+            processedSnapshot = htmlResponse.outerHTML;
+        }
+        else {
+            processedSnapshot = {
+                metadata: {
+                    captureTime: new Date().toISOString(),
+                    method: 'DOM.getOuterHTML',
+                    documentsCount: 1
+                },
+                documents: [{
+                        url: await this.getCurrentURL(client),
+                        title: await this.getCurrentTitle(client),
+                        html: htmlResponse.outerHTML,
+                        domTree: docResponse.root
+                    }]
+            };
+        }
+        if (snapshotArgs.filename) {
+            await this.saveSnapshot(processedSnapshot, snapshotArgs.filename, snapshotArgs.format);
             return {
-                success: false,
-                error: error instanceof Error ? error.message : String(error)
+                success: true,
+                data: {
+                    message: `DOM snapshot saved to ${snapshotArgs.filename}`,
+                    filename: snapshotArgs.filename,
+                    format: snapshotArgs.format || 'json'
+                }
             };
         }
+        return {
+            success: true,
+            data: {
+                snapshot: processedSnapshot,
+                format: snapshotArgs.format || 'json'
+            }
+        };
+    }
+    async getCurrentURL(client) {
+        try {
+            const result = await client.send('Runtime.evaluate', {
+                expression: 'window.location.href',
+                returnByValue: true
+            });
+            return result.result?.value || 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    async getCurrentTitle(client) {
+        try {
+            const result = await client.send('Runtime.evaluate', {
+                expression: 'document.title',
+                returnByValue: true
+            });
+            return result.result?.value || 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
     }
     buildSnapshotParams(args) {
         const params = {};
-        params.computedStyles = args.includeStyles !== false;
-        params.includeDOMRects = args.includeAttributes !== false;
         if (args.includePaintOrder) {
-            params.includePaintOrder = true;
-        }
-        if (args.includeTextIndex) {
-            params.includeTextIndex = true;
+            console.log('Paint order requested but not yet supported');
         }
-        params.computedStyleWhitelist = [];
         return params;
     }
     processSnapshot(response, args) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-cdp-cli",
-  "version": "1.2.2",
-  "description": "Command-line tool for controlling Chrome browser via Chrome DevTools Protocol. Features: JavaScript execution, screenshots, DOM snapshots, console/network monitoring, IDE integration (Cursor commands & Claude skills). Install IDE tools with --force option for directory validation bypass.",
+  "version": "1.2.4",
+  "description": "LLM-first browser automation CLI via Chrome DevTools Protocol. Designed specifically for AI assistants (LLMs) - most commands use eval because LLMs excel at writing JavaScript for rapid script validation. Features: JavaScript execution, screenshots, DOM snapshots, console/network monitoring. Built-in IDE integration: install Cursor commands and Claude skills directly. Perfect for LLM-assisted development workflows where AI writes and tests automation scripts instantly.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {