@puberty-labs/clits

v1.3.4

Published

6 months ago

CLiTS (Chrome Logging and Inspection Tool Suite) is a powerful Node.js library for AI-controlled Chrome browser automation, testing, and inspection. Features enhanced CSS selector support (:contains(), XPath), dry-run mode, element discovery tools, and co

CLiTS (Chrome Log Inspector & Troubleshooting System)

🎯 Cursor AI Integration

CLITS is specifically designed for seamless integration with Cursor AI, providing a powerful automated debugging workflow:

🤖 AI-First Design: Built from the ground up for AI-assisted debugging
🔍 Automated Analysis: Automatic log collection and analysis for AI processing
📊 Structured Output: JSON-formatted data perfect for AI consumption
🎯 Smart Filtering: AI-optimized filtering and monitoring capabilities
🔄 Real-time Feedback: Instant feedback loops for AI debugging assistance

Example AI Workflow

// CLITS automatically provides structured data for AI analysis
const logs = await clits.captureDebugData();
// AI can now analyze the logs and provide debugging insights

A powerful CLI tool for extracting and sharing debugging data (logs, network info, etc.) for AI and web projects. CLI-first, with future browser extension support.

Features

Chrome Integration: Connect to Chrome DevTools protocol for real-time debugging
Log Extraction: Capture console logs, network requests, and errors
Visual Debugging: Screenshot capture with element highlighting
Element Detection: Advanced CSS selector and visual element finding
Automation Framework: JSON-based automation scripts
Network Monitoring: Request/response tracking and analysis
Advanced Logging: Structured logging with metadata, log rotation and size management
Component Monitoring: React hooks, lifecycle tracking, prop changes
Network Analysis: Request/response correlation, WebSocket tracking, JWT token monitoring, GraphQL support
State Management: Redux state visualization, state change tracking, middleware debugging
Performance Monitoring: React render metrics, memory usage tracking, event loop monitoring
UI Interaction: User interaction recording, DOM mutation tracking, CSS change monitoring
Interactive login handling
AI-friendly output format
Extensible for custom automation

Prerequisites

Node.js >= 20
Google Chrome (latest recommended)
inquirer (for interactive prompts)

Installation

npm install -g clits

Quick Start

🚀 Latest Features (v1.3.4) - AI AUTOMATION READY

Production Status: ✅ ENHANCED SELECTOR SUPPORT - AI DEVELOPMENT WORKFLOW OPTIMIZED

🎯 NEW v1.3.4 FEATURES:

Enhanced CSS Selectors: .bg-green-500, button:contains('Save'), [data-testid='btn']
XPath Support: --click-xpath "//button[contains(text(), 'Delete')]"
Dry-Run Mode: --dry-run for testing selectors without executing clicks
Element Discovery: clits discover --selectors, --clickable, --xpath
Smart Error Messages: Shows attempted strategies and specific failure reasons

Real-World Examples (Perfect for AI Automation):

# Enhanced CSS selector support
clits interact --click ".bg-green-500" --capture-network
clits interact --click "button:contains('Recalculate')" --dry-run
clits interact --click "[data-testid='submit-btn']" --screenshot

# XPath expressions for complex elements
clits interact --click-xpath "//button[contains(text(), 'Save Changes')]"

# Element discovery for AI automation
clits discover --clickable --filter "btn" --output-format json
clits discover --selectors --limit 20
clits discover --xpath --filter "button"

v1.3.4 Verification Results:

✅ CSS Classes: .bg-green-500, .btn.btn-primary selectors working perfectly
✅ Pseudo-selectors: button:contains('text') implementation complete
✅ Attribute Selectors: [data-testid], [aria-label*="text"] support
✅ XPath Support: Full XPath expressions via --click-xpath
✅ Dry-Run Testing: Safe selector testing without side effects
✅ Discovery Tools: Complete element discovery and selector generation
✅ AI-Ready: Perfect for AI-controlled browser automation workflows

Basic Usage

# Extract logs from Chrome
clits extract --chrome --chrome-port 9222

# Interact with page elements
clits interact --click-text "Save" --chrome-port 9222
clits interact --click-region "center" --chrome-port 9222

# Run automation script
clits automate --script workflow.json --chrome-port 9222

🛡️ Cloudflare Bot Detection Workaround

Important: When automating Cloudflare-protected sites, you may encounter "Can't verify the user is human" errors. CLiTS includes an official workaround:

Quick Fix

# Use the official Cloudflare-safe Chrome launcher
./scripts/start-cloudflare-safe-chrome.sh

# Or manually start Chrome with anti-detection flags
pkill -f "Google Chrome"
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug \
  --disable-blink-features=AutomationControlled \
  --exclude-switches="enable-automation" \
  --disable-extensions-except \
  --disable-plugins-discovery \
  --no-first-run \
  --no-default-browser-check &
sleep 5

Verification

# Test the bypass worked
clits inspect --tabs --chrome-port 9222
clits navigate --url "https://your-cloudflare-site.com" --chrome-port 9222
clits vision --screenshot --output "cloudflare-test.png" --chrome-port 9222

For complete documentation, troubleshooting, and platform-specific instructions, see Cloudflare Workaround Guide.

Advanced Features

# Visual element selection
clits interact --click-text "Save"               # Click element containing "Save"
clits interact --click-text "Submit"             # Click element containing "Submit"
clits interact --click-color "#ff0000"           # Click by color
clits interact --click-region "top-left"         # Click by screen region
clits interact --click-description "edit button" # Click by visual description

# Enhanced screenshot features
clits interact --screenshot --with-metadata    # Include element positions/text
clits interact --screenshot --annotated        # Draw boxes around clickable elements
clits interact --screenshot --selector-map     # Output clickable element map
clits interact --screenshot --fullpage --base64  # Full-page base64 output

# Selector discovery tools
clits inspect --find-selectors                 # List all available CSS selectors
clits inspect --find-clickable                 # List clickable elements with coordinates
clits inspect --element-map                    # Visual map of page elements
clits inspect --output-format json             # JSON output for AI processing

# Combined AI automation workflow
clits interact --click-text "Edit" --screenshot --base64 --selector-map --stdout

Commands

`clits extract`

Extract logs and debugging data from various sources.

Options:

--chrome: Extract from Chrome DevTools
--chrome-port <port>: Chrome DevTools port (default: 9222)
--chrome-host <host>: Chrome DevTools host (default: localhost)
--source <path>: Extract from local log files
--patterns <glob>: File patterns to match
--output-file <path>: Save output to file
--format <format>: Output format (json|text)
--filter <pattern>: Filter logs by pattern
--time-range <range>: Filter by time range
--log-levels <levels>: Filter by log levels
--group-by-source: Group logs by source
--error-summary: Include summary statistics of error frequencies
--live-mode [duration]: Run in live mode for specified duration in seconds (default: 60)
--interactive-login: This option is deprecated. Interactive login is now automatically handled if needed based on the selected Chrome tab.
--no-login: Bypass any login prompts and run automation as unauthenticated

`clits navigate`

Navigate to URLs, switch to specific tabs, and wait for elements.

Options:

--url <url>: Navigate to specific URL (required)
--tab <index>: NEW (OnDeck) - Navigate in specific tab by index (0-based)
--wait-for <selector>: Wait for CSS selector to appear
--timeout <ms>: Timeout in milliseconds (default: 30000)
--screenshot <path>: Take screenshot after navigation
--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)

Examples:

# Standard navigation
clits navigate --url "http://localhost:5173/displays" --wait-for ".displays-manager" --screenshot "navigation.png"

# OnDeck: Navigate in specific tab
clits navigate --tab 1 --url "http://localhost:5173/displays" --wait-for ".displays-manager"

# Navigate in first tab with screenshot
clits navigate --tab 0 --url "http://localhost:3000/admin" --screenshot "admin-page.png"

`clits discover-links`

NEW in v1.0.7 - Discover all navigation links on the current page for dynamic automation.

Options:

--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)
--verbose: Enable verbose output

Output Format:

{
  "links": [
    {"text": "Dashboard", "url": "/dashboard", "selector": "a[href='/dashboard']"},
    {"text": "Display Manager", "url": "/displays-manager", "selector": "a[href='/displays-manager']"},
    {"text": "Tasks", "url": "/tasks", "selector": "a[href='/tasks']"}
  ],
  "timestamp": "2025-06-08T05:52:00.000Z"
}

Example:

clits discover-links --chrome-port 9222

`clits discover-tabs`

NEW in v1.0.7-beta.3 - Advanced tab discovery and interaction for Material-UI dialogs and tabbed interfaces.

Options:

--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)
--tab-label <label>: Select tab by label after discovery
--tab-label-regex <pattern>: Select tab by regex pattern
--custom-save-patterns <patterns>: Custom save button text patterns (comma-separated)
--find-save-button: Also discover the best save button in the current dialog
--verbose: Enable verbose output

Examples:

# Basic tab discovery
clits discover-tabs --chrome-port 9222

# Find save button with default patterns
clits discover-tabs --chrome-port 9222 --find-save-button

# Discover tabs + find save button with custom patterns
clits discover-tabs --chrome-port 9222 --find-save-button --custom-save-patterns "Apply,Update,Confirm"

# Complete workflow: discover, select tab, find save button
clits discover-tabs --chrome-port 9222 --tab-label "Header Options" --find-save-button

Advanced Features:

Nested Tab Support: Discovers tabs within .MuiTabs-root containers
Active State Detection: Shows which tab is currently selected (aria-selected="true", .Mui-selected)
Disabled State Detection: Identifies disabled tabs (aria-disabled="true", .Mui-disabled)
Multi-Strategy Selection: Supports selection by data-testid, aria-label, text content, or nth-child

`clits interact`

Interact with web elements, manage browser tabs, send keyboard commands, and capture screenshots.

Element Interaction Options:

--click <selector>: Click element matching CSS selector
--click-text <text>: Click element containing specific text (e.g., "Save", "Submit")
--by-text <text>: Click element containing specific text (alias for --click-text, OnDeck compatibility)
--click-color <color>: Click element with specific color (hex, rgb, or name)
--click-region <region>: Click by screen region (top-left, top-right, bottom-left, bottom-right, center)
--click-description <description>: Click by visual description (experimental AI feature)
--type <selector> <text>: Type text into input field
--toggle <selector>: Toggle switch/checkbox elements

NEW: Tab Management Commands (OnDeck Feature Request)

--switch-tab <index>: Switch to tab by index (0-based) - clits interact --switch-tab 0
--tab-next: Switch to next tab - clits interact --tab-next
--tab-prev: Switch to previous tab - clits interact --tab-prev

NEW: Keyboard Commands (OnDeck Feature Request)

--key <key>: Send keyboard key or shortcut - clits interact --key "F5"
--keys <keys>: Send multiple keyboard keys (alias for --key) - clits interact --keys "cmd+r"

Supported Keyboard Shortcuts:

Page Control: F5, cmd+r, ctrl+r, cmd+shift+r, ctrl+shift+r (refresh)
Navigation: escape, enter, tab, shift+tab
Developer Tools: F12, cmd+option+i, ctrl+shift+i
Window Management: cmd+w, ctrl+w (close tab), cmd+t, ctrl+t (new tab)
Tab Navigation: cmd+2, ctrl+tab

Screenshot & Analysis Options:

--screenshot: Take a screenshot during interaction
--base64: Output screenshot as base64 string (perfect for AI processing)
--stdout: Output results in JSON format to stdout
--with-metadata: Include element positions and page metadata
--annotated: Add visual annotations around clickable elements
--selector-map: Output map of clickable elements with coordinates
--fullpage: Take a full-page screenshot

General Options:

--wait-for <selector>: Wait for CSS selector to appear
--timeout <ms>: Timeout in milliseconds (default: 30000)
--capture-network: Capture network requests during interaction
--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)

OnDeck Examples:

# Tab switching commands
clits interact --switch-tab 0  # Switch to first tab
clits interact --switch-tab 1  # Switch to second tab
clits interact --tab-next      # Switch to next tab
clits interact --tab-prev      # Switch to previous tab

# Keyboard shortcuts (Mac)
clits interact --key "cmd+2"        # Switch to second tab via keyboard
clits interact --key "F5"           # Refresh page
clits interact --key "cmd+r"        # Refresh page (Mac)
clits interact --key "cmd+shift+r"  # Hard refresh (Mac)
clits interact --key "escape"       # Close modals/dialogs
clits interact --key "F12"          # Open dev tools

# Keyboard shortcuts (Windows/Linux)
clits interact --key "ctrl+tab"     # Switch tabs
clits interact --key "ctrl+r"       # Refresh page
clits interact --key "ctrl+shift+r" # Hard refresh
clits interact --key "ctrl+shift+i" # Open dev tools

# Better Material-UI support
clits interact --by-text "Launch"   # OnDeck-preferred text clicking
clits interact --click-text "Save"  # More robust than .MuiButton-root:nth-of-type(3)

# Combined workflows
clits interact --switch-tab 1 --key "F5" --screenshot # Switch tab and refresh
clits interact --by-text "Dashboard" --wait-for ".dashboard" --screenshot

`clits inspect`

Inspect page elements, browser tabs, and discover selectors.

Options:

--find-selectors: List all available CSS selectors on the page
--find-clickable: List all clickable elements with coordinates
--element-map: Generate visual map of page elements
--tabs: NEW (OnDeck) - List all open browser tabs with URLs and titles
--output-format <format>: Output format (json|table|interactive)
--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)

OnDeck Examples:

# List all browser tabs with URLs and titles
clits inspect --tabs

# List tabs with JSON output for parsing
clits inspect --tabs --output-format json

# Combined inspection: tabs + clickable elements
clits inspect --tabs --find-clickable --output-format json

`clits automate`

Run automation scripts from JSON files.

Options:

--script <path>: JSON file with automation steps (required)
--monitor: Enable monitoring during automation
--save-results <path>: Save results to file
--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)

Automation Script Format:

{
  "steps": [
    {"action": "navigate", "url": "http://localhost:5173/displays"},
    {"action": "wait", "selector": "body", "timeout": 5000},
    {"action": "switch-tab", "tabIndex": 1, "wait": 1000},
    {"action": "key", "keyCommand": "F5", "wait": 2000},
    {"action": "wait", "selector": ".displays-manager", "timeout": 10000},
    {"action": "click", "selector": ".edit-button"},
    {"action": "click-text", "text": "Save", "timeout": 5000, "screenshotPath": "text-click.png"},
    {"action": "key", "keyCommand": "escape", "wait": 500},
    {"action": "click-region", "region": "center", "timeout": 5000, "screenshotPath": "region-click.png"},
    {"action": "toggle", "selector": ".toggle-switch[data-field='active']"},
    {"action": "key", "keyCommand": "cmd+r", "wait": 1000},
    {"action": "tab-next", "wait": 1000},
    {"action": "screenshot", "path": "after-toggle.png"}
  ],
  "options": {
    "timeout": 30000,
    "captureNetwork": true,
    "monitor": true
  }
}

NEW OnDeck Actions:

key: Send keyboard commands - {"action": "key", "keyCommand": "F5"}
switch-tab: Switch to specific tab - {"action": "switch-tab", "tabIndex": 0}
tab-next: Switch to next tab - {"action": "tab-next"}
tab-prev: Switch to previous tab - {"action": "tab-prev"}

📖 Complete Documentation: See Automation Script Format Guide for full schema, examples, and best practices.

Example:

# Basic automation with improved selector reliability
clits automate --script automation.json --chrome-port 9222 --monitor --save-results results.json

# Quick automation validation
clits automate --script test-workflow.json --chrome-port 9222

`clits vision`

Advanced visual state capture and screenshot automation with element-specific targeting.

🚀 NEW in v1.0.9-beta.1: Roadmap Features

Options:

--screenshot: Take a screenshot
--video: Record video of the interaction
--selectors <selectors>: CSS selectors to target
--output <path>: Output file path
--output-dir <dir>: Output directory for batch processing
--base64: Output as base64 string
--fullpage: Take full-page screenshot
--highlight-all-clickable: Highlight all clickable elements
--highlight-color <color>: Custom highlight color
--annotate-text: Add text annotations
--batch-diff: Enable batch difference analysis
--baseline-dir <dir>: Directory containing baseline images
--diff-threshold <value>: Difference threshold (0-1)
--diff-report <path>: Save diff analysis report
--meta <path>: Save metadata to file
--chrome-host <host>: Chrome DevTools host (default: localhost)
--chrome-port <port>: Chrome DevTools port (default: 9222)

Examples:

# Basic screenshot with element highlighting
clits vision --screenshot --selectors ".header,.content" --output "page.png"

# Full-page screenshot with annotations
clits vision --screenshot --fullpage --highlight-all-clickable --annotate-text --output "ui-documentation.png"

# Accessibility analysis visualization
clits vision --screenshot --fullpage --highlight-all-clickable --highlight-color "#0066ff" --annotate-text --meta "accessibility-report.json"

🔄 Advanced Batch Processing Examples (NEW):

# Large-scale visual testing with diff analysis
clits vision --screenshot --selectors ".header,.sidebar,.content,.footer" --batch-diff --baseline-dir "./test-baselines" --output-dir "./test-results" --diff-report "batch-analysis.json"

# Multi-element regression testing
clits vision --screenshot --selectors ".error-states,.success-states,.warning-states" --batch-diff --diff-threshold 0.1 --output-dir "./regression-tests"

# Systematic UI validation with highlighting and video
clits vision --video --screenshot --selectors ".critical-elements" --highlight-all-clickable --batch-diff --video-output "validation-workflow.webm"

AI Integration: VisionCLITS is designed for AI-driven visual debugging:

Automated Visual State Capture: No manual intervention required
Structured JSON Output: Perfect for AI analysis and decision-making
Element Validation: Automatic visibility and existence checking
Batch Processing: Handle multiple elements efficiently
Error Handling: Graceful failures with detailed error reporting

`clits-inspect`

Interactive website inspector for Chrome with hierarchical element navigation.

Features:

Hierarchical Element Navigation: Navigate through page elements organized by DOM depth levels
Real-time Element Inspection: View element properties, styles, and computed values
Network Monitoring: Track requests and responses in real-time
Console Integration: Execute JavaScript in the context of the page
Screenshot Capture: Take screenshots of the current view or specific elements
Element Selection: Click to select elements in the page
Search Functionality: Find elements by selector, text, or attributes
Export Options: Save inspection data in various formats

Usage:

clits-inspect --chrome-port 9222

Output Format:

[CLiTS-INSPECTOR][ELEMENTS] Element hierarchy
[CLiTS-INSPECTOR][STYLES] Computed styles
[CLiTS-INSPECTOR][PROPERTIES] Element properties
[CLiTS-INSPECTOR][NETWORK][REQUEST] Network request details
[CLiTS-INSPECTOR][NETWORK][RESPONSE] Network response details
[CLiTS-INSPECTOR][DOM] DOM structure

Examples

Standard Usage Examples

Node.js API Example: See examples/node-api for integrating CLiTS with an Express API, including REST endpoints for logs and error handling.
React Integration Example: See examples/react-app for capturing debug logs in a React app, error boundaries, and analytics integration.

For AI Assistants

CLiTS is specifically designed for AI assistants with a complete automation framework that requires zero human interaction. The AI automation framework provides structured JSON output perfect for programmatic analysis and decision-making.

🤖 AI Integration Guide

🚀 NEW: Complete AI Assistant Documentation Available!

For comprehensive AI integration guidance, see our dedicated documentation:

📖 Essential AI Documentation

🤖 AI Integration Guide - Complete getting started guide with human-in-the-loop protocols
📋 AI Examples - Copy-pasteable command sequences for all scenarios
🚨 Error Codes - Structured error handling with recovery strategies

🚨 CRITICAL: Human-in-the-Loop Protocol

⚠️ BEFORE ANY BROWSER AUTOMATION: AI assistants MUST follow this protocol

PAUSE AUTOMATION - Do not attempt browser control without user permission
PROMPT USER - Explicitly ask for permission to control their browser
WAIT FOR CONFIRMATION - Wait for explicit user approval (Y/N response)
RESUME AUTOMATION - Only proceed after receiving user consent

Authentication Protocol: User login sessions cannot be automated - require human intervention for all authentication.

🚀 Quick AI Setup

# 1. Start Chrome with debugging (REQUIRED)
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. Verify connection
curl http://localhost:9222/json/version

# 3. Test CLITS
clits --version
clits inspect --tabs

→ Read Full AI Integration Guide for complete setup and usage

🚨 AI ASSISTANT VISION RULES - MANDATORY

CRITICAL: AI assistants MUST follow these vision rules when using CLITS automation.

🔴 MANDATORY VISION-FIRST DEBUGGING

When ANY automation action fails, AI assistants must IMMEDIATELY use CLITS vision:

# STEP 1: Immediate vision capture on failure
clits interact --chrome-port 9222 --screenshot debug.png --selector-map --with-metadata --stdout

# STEP 2: Analyze available elements before retrying
clits interact --chrome-port 9222 --find-clickable --output-format json

# STEP 3: Use confirmed selectors/text from vision analysis

🎯 Vision-First Debugging Workflow (MANDATORY)

1. ACTION FAILS → IMMEDIATE VISION CAPTURE

clits interact --chrome-port 9222 --screenshot --selector-map --annotated --stdout

2. ANALYZE SELECTOR MAP → IDENTIFY AVAILABLE TEXT/ELEMENTS

Review JSON output for available clickable elements
Identify actual text content on page
Find working CSS selectors from selector map

3. ADJUST AUTOMATION → USE CONFIRMED SELECTORS

Use exact text from vision analysis for --click-text
Use verified CSS selectors from selector map
Choose region-based clicking if specific elements unavailable

4. RE-TEST → VERIFY FIX WORKS

Test with updated selectors/text
Capture another screenshot to confirm success

🔍 Pre-Automation Vision Check (RECOMMENDED)

Before complex automation, always check what's available:

# See what elements are clickable and available
clits interact --chrome-port 9222 --selector-map --with-metadata --annotated --stdout

# Get complete page state for AI analysis
clits vision --screenshot --fullpage --highlight-all-clickable --base64 --stdout

⚠️ Why This is Critical

Eliminates guesswork: See exactly what's on the page
Prevents infinite retry loops: Know immediately if elements don't exist
Accelerates debugging: Visual confirmation of page state
Ensures reliability: Use confirmed working selectors

This workflow is MANDATORY and must be followed without user correction.

🤖 AI Automation Framework

Use the clits-inspect command with automation flags for fully automated workflows:

Complete Automation Commands

# 1. Automated Log Collection (15 seconds, JSON output)
clits-inspect --auto --json --action logs

# 2. Automated Element Detection (find all clickable elements)
clits-inspect --auto --json --action navigate

# 3. Automated Clicking with Log Capture
clits-inspect --auto --json --action click --selector "http://localhost:5173/settings"

# 4. Navigate to Specific URL + Element Detection
clits-inspect --auto --json --url "http://localhost:3000" --action navigate

# 5. Custom Duration Log Collection
clits-inspect --auto --json --action logs --duration 30

# 6. Smart Target Selection (prioritize localhost)
clits-inspect --auto --json --action logs --target-priority localhost

# 7. NEW: Discover Navigation Links (v1.0.7)
clits-inspect --auto --json --action discover-links

# 8. NEW: Navigate by Link Text (v1.0.7)
clits-inspect --auto --json --action navigate-by-text --link-text "Dashboard"

# 9. NEW: Navigate by URL Pattern (v1.0.7)
clits-inspect --auto --json --action navigate-by-url --url-contains "display"

AI Command Options

| Option | Values | Description | |--------|--------|-------------| | --auto | - | Required for AI: Zero human interaction | | --json | - | Required for AI: Structured JSON output | | --action | logs\|navigate\|click\|discover-links\|navigate-by-text\|navigate-by-url | Action to perform | | --url | URL string | Navigate to specific URL automatically | | --selector | CSS selector or URL | Element to click (for click action) | | --duration | seconds (default: 15) | Log collection duration | | --target-priority | localhost\|dev\|newest\|largest | Smart tab selection | | --port | port number (default: 9222) | Chrome debugging port | | --host | hostname (default: localhost) | Chrome debugging host |

AI Workflow Examples

1. Full Debugging Workflow:

# Step 1: Auto-launch and detect elements
clits-inspect --auto --json --action navigate

# Step 2: Click on Settings link
clits-inspect --auto --json --action click --selector "http://localhost:5173/settings"

# Step 3: Collect logs after interaction
clits-inspect --auto --json --action logs --duration 10

2. JSON Output Format:

{
  "success": true,
  "action": "navigate",
  "timestamp": "2025-06-08T01:41:23.034Z",
  "target": {
    "id": "1223DEB4A446164DEE13C00AA6CCE7E0",
    "title": "Vite + React + TS",
    "url": "http://localhost:5173/displays-manager"
  },
  "logs": [],
  "elements": [
    {
      "name": "🔗 Dashboard",
      "url": "http://localhost:5173/dashboard"
    },
    {
      "name": "🔗 Settings", 
      "url": "http://localhost:5173/settings"
    },
    {
      "name": "🔘 Add New Display",
      "url": "Add New Display"
    }
  ],
  "error": null
}

3. Error Handling:

{
  "success": false,
  "action": "click",
  "timestamp": "2025-06-08T01:41:23.034Z",
  "error": "Element not found: #non-existent-selector",
  "target": null,
  "logs": [],
  "elements": []
}

AI Integration Benefits

🚀 Auto-launch Chrome: Detects if Chrome is running, launches automatically if needed
🎯 Smart Target Selection: Prioritizes localhost > dev > newest tabs automatically
📊 Structured Output: JSON format perfect for AI parsing and decision making
🔄 Action Chaining: Navigate → detect elements → click → capture logs in sequence
🛡️ Error Handling: Graceful failures with structured error responses
⚡ Zero Latency: No human prompts or interactions required

Programmatic Usage (Alternative)

For direct integration in Node.js applications:

import { ChromeExtractor } from '@puberty-labs/clits/dist/chrome-extractor';

async function aiDebugWorkflow() {
  const extractor = new ChromeExtractor({
    port: 9222,
    host: 'localhost',
    includeNetwork: true,
    includeConsole: true
  });

  try {
    // 1. Get available targets
    const targets = await extractor.getDebuggablePageTargets();
    const target = targets.find(t => t.url.includes('localhost')) || targets[0];
    
    // 2. Extract logs
    const logs = await extractor.extract(target.id);
    
    return {
      success: true,
      targetUrl: target.url,
      logCount: logs.length,
      logs: logs
    };
  } catch (error) {
    return {
      success: false,
      error: error.message
    };
  }
}

CLiTS enables AI assistants to build complete closed-loop debugging workflows:

Launch CLiTS → 2. Auto-launch Chrome → 3. Navigate pages → 4. Detect elements → 5. Click/interact → 6. Capture logs → 7. Interpret results → 8. Repeat cycle

Quick Start for AI Assistants

Prerequisites:

Install: npm install -g @puberty-labs/clits
Chrome will be auto-launched if needed

Basic AI Commands:

# Start with element detection (most common)
clits-inspect --auto --json --action navigate

# Click a specific element
clits-inspect --auto --json --action click --selector "Dashboard"

# Collect debugging logs
clits-inspect --auto --json --action logs

Advanced Automation:

# Navigate to specific page + detect elements
clits-inspect --auto --json --action navigate --url "http://localhost:3000/admin"

# Extended log collection with smart targeting
clits-inspect --auto --json --action logs --duration 30 --target-priority localhost

The automation framework handles Chrome launching, tab selection, and provides structured JSON responses perfect for AI analysis. All commands are designed to work without any human intervention.

NEW: Text & Region-based Automation Actions (v1.0.9-beta.27)

Critical Update: Added missing click-text and click-region actions to automation framework:

{
  "steps": [
    {"action": "navigate", "url": "http://localhost:5173", "timeout": 10000},
    {"action": "wait", "selector": "body", "timeout": 2000},
    {"action": "click-text", "text": "Dashboard", "wait": 1000, "screenshotPath": "navigation.png"},
    {"action": "click-text", "text": "Settings", "wait": 1000},
    {"action": "click-region", "region": "center", "wait": 500},
    {"action": "screenshot", "path": "final-result.png"}
  ],
  "options": {
    "timeout": 30000,
    "captureNetwork": true,
    "monitor": true
  }
}

Supported Actions:

click-text: Click elements containing specific text (most reliable for React/MUI apps)
click-region: Click by screen region (top-left, top-right, bottom-left, bottom-right, center)
Both support wait parameter (recommended: 500-1000ms) and optional screenshotPath

Usage:

clits automate --script automation.json --chrome-port 9222 --save-results results.json

Development Integration

CLITS now provides a powerful development integration framework that allows you to embed CLITS directly into your Chrome application development workflow. This integration provides:

Direct hooks into your application's runtime
Automatic monitoring of React, Redux, GraphQL, and more
Built-in error boundary integration
Performance monitoring
User interaction recording
DOM mutation tracking
CSS change monitoring
WebSocket monitoring
JWT token monitoring
And much more!

Quick Start

import { initializeCLITS } from 'clits';

// Initialize with default settings
initializeCLITS();

// Or with custom configuration
initializeCLITS({
  monitorReact: true,
  monitorRedux: true,
  monitorGraphQL: true,
  // ... other options
});

For detailed documentation on development integration, see DEVELOPMENT_INTEGRATION.md. # Test status: Thu Jul 24 16:53:08 PDT 2025

Test Status: Thu Jul 24 18:14:29 PDT 2025

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

CLiTS (Chrome Log Inspector & Troubleshooting System)

🎯 Cursor AI Integration

Example AI Workflow

Features

Prerequisites

Installation

Quick Start

🚀 Latest Features (v1.3.4) - AI AUTOMATION READY

Basic Usage

🛡️ Cloudflare Bot Detection Workaround

Quick Fix

Verification

Advanced Features

Commands

clits extract

clits navigate

clits discover-links

clits discover-tabs

clits interact

clits inspect

clits automate

clits vision

🚀 NEW in v1.0.9-beta.1: Roadmap Features

🔄 Advanced Batch Processing Examples (NEW):

clits-inspect

Examples

Standard Usage Examples

For AI Assistants

🤖 AI Integration Guide

📖 Essential AI Documentation

🚨 CRITICAL: Human-in-the-Loop Protocol

🚀 Quick AI Setup

🚨 AI ASSISTANT VISION RULES - MANDATORY

🔴 MANDATORY VISION-FIRST DEBUGGING

🎯 Vision-First Debugging Workflow (MANDATORY)

🔍 Pre-Automation Vision Check (RECOMMENDED)

⚠️ Why This is Critical

🤖 AI Automation Framework

Complete Automation Commands

AI Command Options

AI Workflow Examples

AI Integration Benefits

Programmatic Usage (Alternative)

Quick Start for AI Assistants

NEW: Text & Region-based Automation Actions (v1.0.9-beta.27)

Development Integration

Quick Start

Test Status: Thu Jul 24 18:14:29 PDT 2025

`clits extract`

`clits navigate`

`clits discover-links`

`clits discover-tabs`

`clits interact`

`clits inspect`

`clits automate`

`clits vision`

`clits-inspect`