JS Eyes

JS Eyes

Browser extension + WebSocket server that gives AI agents full browser automation capabilities.

What it does

JS Eyes connects a browser extension (Chrome / Edge / Firefox) to an AI agent framework via WebSocket, enabling the agent to:

• List and manage browser tabs
• Open URLs and navigate pages
• Extract full HTML content from any tab
• Execute arbitrary JavaScript in page context
• Read cookies for any domain
• Monitor connected browser clients

Architecture

Browser Extension  <── WebSocket ──>  JS-Eyes Server  <── WebSocket ──>  AI Agent (OpenClaw)
 (Chrome/Edge/FF)                     (Node.js)                         (Plugin: index.mjs)

The browser extension runs in the user's browser and maintains a persistent WebSocket connection to the JS-Eyes server. The OpenClaw plugin connects to the same server and exposes 7 AI tools + a background service + CLI commands.

Provided AI Tools

CLI Commands

openclaw js-eyes status          # Server connection status
openclaw js-eyes tabs            # List all browser tabs
openclaw js-eyes server start    # Start the built-in server
openclaw js-eyes server stop     # Stop the built-in server

Skill Bundle Structure

This skill bundle is published from the repository root and contains all files required to run the OpenClaw plugin:

js-eyes/
├── SKILL.md                        ← Skill entry point (this file)
├── package.json                    ← Root package — declares ws dependency
├── LICENSE
├── openclaw-plugin/
│   ├── openclaw.plugin.json        ← Plugin manifest (ID, config schema, UI hints)
│   ├── package.json                ← ESM module descriptor, declares entry point
│   └── index.mjs                   ← Plugin logic — registers 7 AI tools, 1 service, CLI
├── server/
│   ├── index.js                    ← HTTP + WebSocket server
│   ├── ws-handler.js               ← Connection and message handling
│   └── package.json
└── clients/
    └── js-eyes-client.js           ← Node.js client SDK for browser automation

openclaw-plugin/index.mjs imports from ../server/ and ../clients/ via relative paths, so the directory layout above must be preserved — openclaw-plugin/ cannot be used in isolation.

Prerequisites

• Node.js >= 16
• A supported browser: Chrome 88+ / Edge 88+ / Firefox 58+

Deploy to .openclaw

Install the skill via ClawHub:

clawhub install js-eyes

ClawHub installs into ./skills under your current working directory (or your configured OpenClaw workspace). The bundle is self-contained — it includes the plugin, WebSocket server, and client SDK.

1. Install Node.js dependencies — the ws package is required at runtime:

cd ./skills/js-eyes   # from the dir where you ran clawhub install; or ~/.openclaw/skills/js-eyes if using legacy sync
npm install

Run npm install if ws was not auto-installed via the Skills UI.

2. Register the plugin in ~/.openclaw/openclaw.json. The path must point to the openclaw-plugin subdirectory inside the skill, not the skill root:

Example config (replace the path with your actual install location — use pwd after cd into the skill to get the absolute path). If you already have other plugins, append this path to the existing paths array:

{
  "plugins": {
    "load": {
      "paths": ["/path/to/skills/js-eyes/openclaw-plugin"]
    },
    "entries": {
      "js-eyes": {
        "enabled": true,
        "config": {
          "serverPort": 18080,
          "autoStartServer": true
        }
      }
    }
  }
}

Path note: index.mjs imports from ../server/ and ../clients/ relative to itself, so the bundle directory layout must be preserved. Point paths at the openclaw-plugin subdirectory only.

3. Restart OpenClaw to load the plugin.

For developers: clone the full repository and point plugins.load.paths to the openclaw-plugin directory inside your clone.

Browser Extension Setup

The plugin talks to browsers through the JS Eyes extension. Install it separately (independent of ClawHub):

1. Download from GitHub Releases:

   • Chrome / Edge: js-eyes-chrome-vX.Y.Z.zip — open chrome://extensions/ (or edge://extensions/), enable Developer mode, click "Load unpacked", select the extracted folder
   • Firefox: js-eyes-firefox-vX.Y.Z.xpi — drag and drop into the browser window

2. Click the JS Eyes extension icon in the toolbar, enter http://localhost:18080 as the server address, click Connect — the status should turn green.

Verify

Run the CLI command to confirm everything is working:

openclaw js-eyes status

Expected output:

=== JS-Eyes Server Status ===
  Uptime: ...s
  Browser extensions: 1
  Automation clients: ...

You can also ask the AI agent to list your browser tabs — it should invoke js_eyes_get_tabs and return the tab list.

Plugin Configuration

Troubleshooting

Links

• Source: https://github.com/imjszhang/js-eyes
• Releases: https://github.com/imjszhang/js-eyes/releases
• ClawHub: https://clawhub.ai/skills/js-eyes
• Author: @imjszhang
• License: MIT