JS Eyes

Browser Automation and Skills for AI Agent Frameworks

Give your AI agents real eyes into the browser through a standalone server, CLI, MCP facade, or optional OpenClaw integration

English | 中文文档

Quick Install

Linux / macOS:

curl -fsSL https://js-eyes.com/install.sh | bash

Windows (PowerShell):

irm https://js-eyes.com/install.ps1 | iex

This installs the standalone JS Eyes runtime and skill bundle. OpenClaw registration is optional and can be added later; plugin mode expects Node.js 22+. See Manual Installation for other options.

Optional: Auto-sync token to browser extensions

After installing the CLI (npm i -g js-eyes or as part of the skill install flow), register a Native Messaging host so the extension can read server.token locally without manual copy-paste:

npx js-eyes native-host install --browser all

See docs/native-messaging.md for details and the threat model — the NM path defends against external web-page attacks only; a compromised local device is out of scope.

Introduction

JS Eyes is a browser extension + WebSocket server that gives AI agents full browser automation capabilities. It connects to AI agent frameworks (OpenClaw, DeepSeek Cowork, or custom) and provides tools for tab management, content extraction, script execution, cookie access, and more.

Browser Extension  <── WebSocket ──>  JS-Eyes Server  <──>  CLI / MCP / optional OpenClaw
 (Chrome/Edge/FF)                     (packages/server-core)       (independent host integrations)

Monorepo Layout

JS Eyes now uses a publish-oriented monorepo layout:

Path	Purpose
`apps/cli`	Public `js-eyes` npm CLI
`apps/native-host`	Browser Native Messaging host for auto-injecting `server.token`
`packages/protocol`	Shared protocol constants, browser operations, compatibility matrix
`packages/skill-install`	Skill discovery, install, trust, and registry helpers
`packages/policy`	Host-neutral policy context (egress / taint / task-origin)
`packages/runtime-paths`	Runtime directories and filesystem layout
`packages/config`	CLI config loading and persistence (`~/.js-eyes` + `JS_EYES_*`)
`packages/client-sdk`	Browser automation SDK for Node.js / skills
`packages/skill-runtime` / `skill-scaffold`	Host-neutral Skill Runtime V2 and scaffolding
`packages/server-core`	HTTP + WebSocket server core
`packages/mcp-server`	Native stdio MCP facade for Codex, Claude, Cursor, and other MCP clients
`openclaw-plugin`	Optional OpenClaw adapter (`@js-eyes/openclaw-plugin` workspace)
`packages/visual-*`	Skill-optional visual bridge / replay libraries (not platform runtime)
`packages/devtools`	Internal build/release tooling
`extensions/*`	Browser extension assets; `extensions/shared` is the canonical cross-browser background runtime
`skills/*`	Independent site skills

Configuration entry point for operators is ~/.js-eyes plus JS_EYES_* environment variables. MCP-specific JS_EYES_MCP_* flags override the same config layer. OpenClaw legacy openclaw.json skill enablement is migrated read-only and is not a second source of truth.

Development

Development requires Node.js 22 or newer. Install the committed dependency graph with npm ci, then run npm test, npm run lint, npm run typecheck, npm run scan:security, npm audit, and npm run package:smoke before opening a pull request. See CONTRIBUTING.md for build commands, dependency policy, and the complete contribution workflow. Security issues should be reported privately as described in SECURITY.md.

Supported Agent Frameworks

Framework	Description
MCP clients + `@js-eyes/mcp-server`	Native stdio MCP facade with a safe-by-default browser tool profile
apps/cli + packages/server-core	Lightweight built-in server and published npm CLI
OpenClaw + openclaw-plugin	Registers as OpenClaw plugin — 1 AI tool (`js-eyes` router), background service, CLI commands
DeepSeek Cowork	Full-featured agent framework (separate WS port, HMAC auth, SSE, rate limiting)

Native MCP Server

JS Eyes can be used by any local MCP client without loading the OpenClaw plugin. Start the normal JS Eyes server and browser extension, then configure the client to spawn the stdio facade:

{
  "mcpServers": {
    "js-eyes": {
      "command": "npx",
      "args": ["-y", "@js-eyes/mcp-server"]
    }
  }
}

The default safe profile excludes JavaScript execution, cookies, CSS injection, and file upload. See docs/mcp.md for tool profiles, target selection, environment variables, and troubleshooting.

Features

Real-time WebSocket Communication — Persistent connection with server
Auto Server Discovery — Automatic capability detection and endpoint configuration
Tab Management — Auto-sync tab information to server
Remote Control — Remote open/close tabs, execute scripts
Content Retrieval — Get page HTML, text, links
Cookie Management — Auto-retrieve and sync page cookies
Code Injection — JavaScript execution and CSS injection
Health Check & Circuit Breaker — Service health monitoring with automatic circuit breaker protection
Rate Limiting & Deduplication — Request rate limiting and deduplication for stability
Native Messaging Token Sync (2.4.0+) — Browser extensions auto-fetch server.token and HTTP URL from the local CLI via Native Messaging; no manual copy-paste in the default flow
Bearer Token Authentication — Browser extensions authenticate WebSocket upgrades via Sec-WebSocket-Protocol: bearer.<token>; the server also accepts the SDK form jse-token.<token> and the legacy loopback-only ?token=<token> fallback. Anonymous mode gated by security.allowAnonymous
Extension Skills — Discover and install higher-level skills (e.g. X.com search) on top of base automation

Supported Browsers

Browser	Version	Manifest
Chrome	88+	V3
Edge	88+	V3
Firefox	58+	V2

Download

Download the latest release from GitHub Releases:

Chrome/Edge Extension: release asset js-eyes-chrome-v<version>.zip
Firefox Extension: release asset js-eyes-firefox-v<version>.xpi

Or download directly from js-eyes.com. The Chrome and Firefox buttons on the website open the latest GitHub release so they always point at the current published assets.

Manual Installation

Browser Extension

Chrome / Edge

From a release zip (recommended): download js-eyes-chrome-v<version>.zip, extract it, then Load unpacked on the extracted folder.

From this repo (development):

npm run sync:extension-shared   # or: npm run build:chrome

Open chrome://extensions/ (or edge://extensions/)
Enable "Developer mode"
Click "Load unpacked"
Select dist/extensions-stage/chrome (not extensions/chrome — shared runtime is injected into the staged tree at build/sync time)

Raw execute_script support on Chrome/Edge additionally requires version 135+. On version 138+, open the extension details and enable Allow User Scripts; on versions 135-137, keeping Developer mode enabled is sufficient. Other extension features remain available on the baseline versions above.

Firefox

Signed XPI (recommended): drag and drop the .xpi file into Firefox.

Temporary (development):

npm run sync:extension-shared   # or: npm run build:firefox:dev

Then open about:debugging > This Firefox > Load Temporary Add-on > select dist/extensions-stage/firefox/manifest.json.

OpenClaw Skill Bundle

If you prefer manual setup instead of the one-command install:

Download js-eyes-skill.zip from js-eyes.com, or the versioned js-eyes-skill-v<version>.zip asset (e.g. js-eyes-skill-v2.6.3.zip) from GitHub Releases
Extract to a directory (for example ./skills/js-eyes)
Run npm install inside the extracted folder with Node.js 22 or newer
Register the plugin in the resolved OpenClaw config file (see OpenClaw Plugin)

npm link Development Mode

If you want to use the public js-eyes command shape while debugging the current source tree, you can link the published CLI workspace into your global npm bin directory:

cd /path/to/your/js-eyes-repo
npm install

cd apps/cli
npm link

After that, js-eyes resolves to the local apps/cli workspace, so changes in apps/cli and the runtime workspace packages under packages/* are picked up immediately.

On Windows, replace which js-eyes with where js-eyes.

which js-eyes
js-eyes --help
js-eyes doctor

If you also want the linked CLI to run skills directly from this repository instead of the default runtime directory, point skillsDir at the repo's skills/ folder:

js-eyes config set skillsDir "/absolute/path/to/js-eyes/skills"
js-eyes skills enable js-x-ops-skill
js-eyes skill run js-x-ops-skill search "AI agent" --max-pages 2

To return to a normal global install later:

cd /path/to/your/js-eyes-repo/apps/cli
npm unlink
npm uninstall -g js-eyes

Usage

1. Start a Compatible Server

Option A — Built-in lightweight server:

npm run server
# Starts on http://localhost:18080 (HTTP + WebSocket)

Or, after publishing the CLI:

js-eyes server start
js-eyes doctor

Option B — Use as an OpenClaw plugin (see OpenClaw Plugin section below).

Option C — Use a supported agent framework such as DeepSeek Cowork.

2. Configure Connection

Default flow (2.4.0+, recommended) — install the Native Messaging host once and the extension auto-syncs both the server URL and server.token:

npx js-eyes native-host install --browser all

Open the popup and click Sync Token From Host (or simply wait for the auto-sync on startup) — the connection status should flip to "Connected" without any manual input.

Manual fallback — if Native Messaging is unavailable, expand Advanced in the popup and:

Enter the server HTTP address (e.g. http://localhost:18080) and click Connect
Paste server.token contents into Server Token (2.2.0+) (run js-eyes server token show --reveal to retrieve it) and click Save

Auto-Connect: the extension reconnects automatically on startup and after disconnections (exponential backoff); toggle it off under Advanced if you need manual control.

2.2.0 is security-hardened by default. Connections without a matching server token are rejected unless you set security.allowAnonymous=true in config.json. See SECURITY.md and the 2.2.0 migration guide.

2.3.0 adds a non-interactive policy engine (task origin + taint + egress allowlist) in front of every sink. Default enforcement=soft keeps existing workflows working; see the 2.3.0 migration guide.

3. Verify Connection

openclaw js-eyes status

Expected output shows server uptime, connected extensions, and tab count.

4. Manage Skills from the CLI

js-eyes now acts as the host for extension skills as well:

# List remote + installed skills (shows "Update available" when the registry is newer)
js-eyes skills list

# Install and enable a skill
js-eyes skills install js-x-ops-skill
js-eyes skills enable js-x-ops-skill

# Update a single sub-skill to the latest version published in the registry
js-eyes skills update js-x-ops-skill

# Update every primary-source sub-skill in one shot
js-eyes skills update --all

# Preview what would change without touching the installed skill
js-eyes skills update js-x-ops-skill --dry-run

# Run a skill command through the js-eyes host
js-eyes skill run js-x-ops-skill search "AI agent" --max-pages 2

Skill install state is tracked by the JS Eyes runtime config. OpenClaw only needs to load the main js-eyes plugin; the main plugin auto-discovers enabled local skills from the same runtime skills/ directory when it starts.

skills update preserves the user's skillsEnabled state and verifies the downloaded bundle against the registry's sha256. If the registry entry declares minParentVersion higher than the installed js-eyes parent skill, the update is blocked with exit code 2 and the operator is asked to upgrade the parent first.

Starting with 2.2.0, install_skill only writes a plan under runtime/pending-skills/<id>.json. Operators finalize with js-eyes skills approve <id> and enable with js-eyes skills enable <id>. See SECURITY.md.

Security Posture (2.10.0)

The table below summarises the attack surface js-eyes exposes, what the stock install ships with, and the single-knob tightening path for each. Every row links to a section of SECURITY_SCAN_NOTES.md that explains the trade-off in full.

Risk item	Current default	How to tighten	Config switch	Verify
Host-side raw JavaScript eval (`execute_script` family)	`allowRawEval=false`, including the distributable parent Skill	Leave `false`; use the MCP `safe` profile and first-class or read-only operations	`security.allowRawEval` in `~/.js-eyes/config/config.json` (notes)	`js-eyes doctor --json \| jq '.security.allowRawEval'`
Plugin auto-starts embedded WS/HTTP server	`autoStartServer=true`, loopback-only bind, token required	Set `autoStartServer=false` and start the server manually with `js-eyes server start`	`plugins.entries["js-eyes"].config.autoStartServer` in `openclaw.json` (notes)	`js-eyes doctor` → Server section
Single OpenClaw tool exposes the JS Eyes router	`tools.alsoAllow: ["js-eyes"]` + per-action `confirm` gate on sensitive actions	Keep only `js-eyes` allowed; tighten individual actions with `security.toolPolicies`	`tools.allow` / `security.toolPolicies` (notes)	`js-eyes consent list` + `js-eyes doctor`
`extraSkillDirs` skipped integrity verification	New switch off — 2.6.1 behaviour preserved	Set `security.verifyExtraSkillDirs=true`; `skills link` then auto-snapshots, `skills relink` after reviewed edits	`security.verifyExtraSkillDirs` in `~/.js-eyes/config/config.json` (notes)	`js-eyes doctor` prints `integrity: verified \| drifted \| missing-snapshot` per extra; `js-eyes doctor --json` exposes it on each skill row
Native-host install path runs remote code (`npx`)	`npx js-eyes native-host install` remains supported (does not seed the server token)	Use the local launcher `bin/js-eyes-native-host-install.sh \| .ps1` — zero network and 2.6.3+ also runs `js-eyes server token init` so popup Sync Token From Host works on first try	none — doc-only change in 2.6.2 (notes)	`node apps/cli/bin/js-eyes.js native-host status` + `js-eyes server token show`
Server token handling	Generated on demand, file `0600` / Windows `icacls`, bearer on WS + HTTP	Keep defaults; rotate periodically; never set `allowAnonymous=true` in production	`security.allowAnonymous`, `js-eyes server token rotate` (notes)	`js-eyes doctor` → Token section; `js-eyes audit tail`
npm install path (`installSkillDependencies`)	`spawnSync` with whitelisted argv, `shell:false`, filtered env (safe-npm.js)	Enforce strict lockfile usage so remote tarballs must match	`plugins.entries["js-eyes"].config.requireLockfile=true` (notes)	`node --test packages/skill-install/tests/safe-npm.test.js`

Run js-eyes doctor --json to get the live machine-readable snapshot of every row above; pipe to jq or your auditor's tool of choice.

5. Security Quickstart (2.2.0+ / 2.3.0+)

# Generate / inspect / rotate the local server token
js-eyes server token init
js-eyes server token show --reveal
js-eyes server token rotate

# Tail the audit log (JSONL)
js-eyes audit tail

# Review and approve sensitive tool calls awaiting consent
js-eyes consent list
js-eyes consent approve <consent-id>

# 2.3.0+: Policy engine enforcement and pending-egress
js-eyes security show
js-eyes security enforce <off|soft|strict>    # soft is the 2.3.0 default
js-eyes egress list
js-eyes egress approve <id>                   # allow this destination for the session
js-eyes egress allow <domain>                 # permanent allowlist entry

# Two-step skill install with integrity pinning
js-eyes skills install js-x-ops-skill   # writes a plan; prompts to approve
js-eyes skills approve js-x-ops-skill
js-eyes skills enable js-x-ops-skill
js-eyes skills verify                   # re-check .integrity.json across installed skills

# One-shot posture check (includes 2.3 policy engine report)
js-eyes doctor

Secure defaults in 2.2.0:

WebSocket/HTTP require a bearer token and an allow-listed Origin; non-loopback host binds require security.allowRemoteBind=true.
execute_script, get_cookies*, upload_file*, inject_css, and install_skill default to the confirm policy and require a consent approval.
Raw eval-style scripts are refused unless security.allowRawEval=true. The host pushes this value to the extension at init_ack handshake, so a single toggle in ~/.js-eyes/config/config.json is enough; the chrome.storage.local.allowRawEval key is retained only as an explicit opt-out override for hardened deployments. Prefer execute_action for declarative actions when possible.
config.json, server.token, audit.log, and pending-consents files are written at 0600 on POSIX and locked via icacls on Windows.

New in 2.3.0:

A non-interactive policy engine (task origin, taint, egress allowlist) is wired through BrowserAutomation and server-side dispatch. Default enforcement=soft means no hard rejects — violating openUrl calls become pending-egress records, other sinks return POLICY_SOFT_BLOCK for the agent to re-plan.
Every returned cookie is tagged with a canary (__canary: "jse-c-..."); sinks that serialize a canary or a raw cookie value are soft-blocked.
HTTP responses from server-core now carry Content-Security-Policy: default-src 'none', X-Content-Type-Options: nosniff, X-Frame-Options: DENY.

Compatibility escape hatches (use sparingly):

security.allowAnonymous=true accepts unauthenticated clients during a migration — every anonymous session is audited and js-eyes doctor will flag it.
security.toolPolicies.<tool>=allow restores pre-2.2.0 behavior for a specific tool.
js-eyes security enforce off (or JS_EYES_POLICY_ENFORCEMENT=off) turns the 2.3 policy engine into audit-only mode.

CLI Runtime Directory

By default, the published js-eyes CLI now stores config, logs, downloads, cache, and installed skills under ~/.js-eyes on macOS, Linux, and Windows.

macOS: ~/.js-eyes
Linux: ~/.js-eyes
Windows: %USERPROFILE%/.js-eyes

If an older installation exists in a legacy OS-specific runtime directory, js-eyes migrates it automatically on first run:

macOS: ~/Library/Application Support/js-eyes
Linux: $XDG_CONFIG_HOME/js-eyes or ~/.config/js-eyes
Windows: %APPDATA%/js-eyes

If JS_EYES_HOME is set, that override still takes precedence and automatic migration is skipped.

OpenClaw Plugin

JS Eyes registers as an OpenClaw plugin, exposing one js-eyes tool that routes browser automation and extension-skill actions.

For native plugin loading, follow the OpenClaw runtime requirements for external plugins (ESM + Node 22+).

What It Provides

Background Service — Automatically starts/stops the built-in WebSocket server
1 AI Tool — js-eyes, with path-style actions for browser automation and skill management
CLI Commands — openclaw js-eyes status, openclaw js-eyes tabs, openclaw js-eyes server start/stop

Action	Description
`browser/get-tabs`	List all open browser tabs with ID, URL, title
`browser/list-clients`	List connected browser extension clients
`browser/open-url`	Open a URL in a new or existing tab
`browser/close-tab`	Close a tab by ID
`browser/get-html`	Get full HTML content of a tab
`browser/execute-script`	Run JavaScript in a tab and return the result
`browser/get-cookies`	Get all cookies for a tab's domain
`skills/discover`	Query the skill registry for available extension skills
`skills/plan-install`	Download, verify, and stage an extension-skill install plan

Setup

Use this order for the standard ClawHub/OpenClaw install path:

Install the browser extension in Chrome/Edge/Firefox (same as above)
Run npm install in the skill root with Node.js 22+
Resolve the OpenClaw config path using this precedence:
- OPENCLAW_CONFIG_PATH
- OPENCLAW_STATE_DIR/openclaw.json
- OPENCLAW_HOME/.openclaw/openclaw.json
- default ~/.openclaw/openclaw.json
Add the plugin to the resolved OpenClaw config:

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

Restart or refresh OpenClaw — the server launches automatically and AI agents can control the browser via registered tools.

For local source-repo development, point plugins.load.paths directly to the repo-root openclaw-plugin directory inside your clone.

Plugin Configuration

Option	Type	Default	Description
`serverHost`	string	`"localhost"`	Server listen address
`serverPort`	number	`18080`	Server port
`autoStartServer`	boolean	`true`	Auto-start server when plugin loads
`requestTimeout`	number	`1800`	Request timeout in seconds (default 30 minutes; server reads this value on startup)
`skillsRegistryUrl`	string	`"https://js-eyes.com/skills.json"`	URL of the extension skill registry
`skillsDir`	string	`""`	Primary skill install directory — empty = auto-detect `skills/` under skill root. All `install` / `approve` / `uninstall` / integrity checks target this directory only.
`extraSkillDirs`	string[]	`[]`	Additional read-only skill sources. An entry can be a V2 directory containing `skill.manifest.json`, or a parent directory scanned one level deep. Primary wins on id conflicts. V1 `skill.contract.js` directories are no longer activated.
`externalSkills.policy`	string	`"prompt"`	External Skill policy: `prompt` or `strict`. Both require approval bound to path, manifest, source/dependency digest, and execution mode. `legacy` is rejected and normalized to `prompt` with a warning.
`externalSkills.defaultExecution`	string	`"worker"`	Execution mode recorded when external V2 Skills are approved: `worker` or `in-process`. Worker is an isolation boundary, not an OS sandbox.

Compatibility Matrix

js-eyes doctor now prints the local package versions, server protocol version, and compatibility status. The current expected matrix is:

Surface	Expected version
Protocol	`1.0`
CLI	`2.10.0`
Browser extension assets	`2.10.0`
`@js-eyes/server-core`	`2.10.0`
`@js-eyes/client-sdk`	`2.10.0`
`@js-eyes/skill-runtime`	`2.10.0`
`openclaw-plugin`	`2.10.0`
Bundled sub-skills (`skills/*`)	Independent semver — see each skill's `package.json` or `dist/skills.json`

Extension Skills

JS Eyes supports extension skills — higher-level capabilities built on top of the base browser automation. First-party Skills are published independently through the registry, so operators install only the platforms they need after the base runtime works. A source checkout also contains their sources under skills/.

The recommended hosting model is now:

declare tools statically in a V2 skill.manifest.json
invoke the shared Skill Runtime from CLI, MCP, or the optional OpenClaw adapter

Migration note: child skills no longer ship their own openclaw-plugin wrapper files. OpenClaw loads only the main js-eyes adapter, which routes enabled local Skills through the same runtime used by CLI and MCP.

Skill	Description	Example tools
js-browser-ops-skill	Generic page read, DOM interact, screenshot	`browser_read_page`, `browser_screenshot`
js-x-ops-skill	X.com search, timelines, posting, official API v2	`x_search_tweets`, `x_get_profile`, `x_get_post`
js-reddit-ops-skill	Reddit browse, search, comments	`reddit_search`, `reddit_get_post`
js-github-ops-skill	GitHub repo / issue / PR operations	platform-specific tools in contract
js-hn-ops-skill	Hacker News front page, items, search	`hn_get_front_page`, `hn_get_item`, `hn_search`
js-zhihu-ops-skill	Zhihu content operations	`zhihu_search`, `zhihu_get_answer`
js-xiaohongshu-ops-skill	Xiaohongshu (RED) content ops	contract tools
js-bilibili-ops-skill	Bilibili video / user ops	contract tools
js-youtube-ops-skill	YouTube browse / search	contract tools
js-wechat-ops-skill	WeChat public account ops	contract tools
js-jike-ops-skill	Jike (即刻) content ops	contract tools

Full registry (versions, sha256, minParentVersion): dist/skills.json after npm run build:site, or live at js-eyes.com/skills.json.

Discovering Skills

AI agents can discover available skills automatically:

# Via the js-eyes AI tool
tool: js-eyes
action: skills/discover

# Via the skill registry
https://js-eyes.com/skills.json

Installing Extension Skills

One-command install (and upgrade):

# Linux / macOS (arg)
curl -fsSL https://js-eyes.com/install.sh | bash -s -- js-x-ops-skill

# Linux / macOS (env var, same as PowerShell)
curl -fsSL https://js-eyes.com/install.sh | JS_EYES_SKILL=js-x-ops-skill bash

# Upgrade every installed sub-skill in one go
curl -fsSL https://js-eyes.com/install.sh | JS_EYES_SKILL=all bash

# Windows PowerShell
$env:JS_EYES_SKILL="js-x-ops-skill"; irm https://js-eyes.com/install.ps1 | iex

Re-running install.sh for a sub-skill that is already installed is safe: the script reads the local package.json version, compares it against the registry, and reports up to date when they match. When the registry is newer it upgrades in place (no Overwrite? prompt) after verifying the bundle sha256. JS_EYES_SKILL=all iterates every directory under <install-dir>/js-eyes/skills/.

Via AI agent: the agent calls the js-eyes tool with action: skills/plan-install and the skill ID in args. It downloads, verifies, and stages an install plan; finalize with js-eyes skills approve <id> and js-eyes skills enable <id>. The main plugin then hot-loads the skill via SkillRegistry + chokidar within ~300 ms — no OpenClaw restart needed for new skill actions.

Via the js-eyes CLI:

js-eyes skills install js-x-ops-skill
js-eyes skills enable js-x-ops-skill
js-eyes skill run js-x-ops-skill search "AI agent" --max-pages 2
js-eyes skill call js-x-ops-skill x_get_profile --args '{"username":"openai"}' --json

Manual: download the skill zip from js-eyes.com/skills/js-x-ops-skill/, extract to skills/js-eyes/skills/js-x-ops-skill/, run npm install, then js-eyes skills enable js-x-ops-skill. A running OpenClaw + js-eyes plugin will hot-load the skill via the config watcher; call js-eyes skills reload or action: skills/reload through the js-eyes tool to force a reload.

Authoring your own JS Eyes Skill

Custom skills don't have to live inside this repository. Two ways to hook them in:

Point skillsDir at the parent folder that contains your skills (js-eyes takes full lifecycle ownership — install / approve / verify all act on this dir).
Keep the default skillsDir and add individual skill folders (or parent folders) to extraSkillDirs. Extras are read-only: they're discovered and routed through js-eyes, but js-eyes never mutates them.

The fastest path for an external custom skill is zero-restart: js-eyes skills link /abs/path/to/my-skill appends the directory to extraSkillDirs. For V2 Skills, review it with js-eyes skills inspect <id> and js-eyes skills permissions <id>, then approve it using js-eyes skills trust <id> --execution worker. Changes to the path, manifest, source files, installed dependencies, capabilities, or execution mode invalidate approval. Use skills revoke, unlink, and reload for the remaining lifecycle.

See:

Skill Runtime V2 architecture — host contract, trust, Worker isolation, and shared host surfaces.
docs/dev/js-eyes-skills/ — authoring and deployment guides. V1 contracts remain supported during migration.
examples/js-eyes-skills/js-hello-ops-skill/ — minimal runnable sample (one tool, no side effects).

The runtime packages are published to the js-eyes npm organization under the @js-eyes/* scope, so external skills can depend on them directly:

npm install @js-eyes/client-sdk @js-eyes/config @js-eyes/skill-recording

@js-eyes/* scope is reserved for official packages published by this repository's maintainers. Third-party JS Eyes Skills and integrations must publish under their own npm scope (e.g. @acme/js-my-cool-skill) or an unscoped name, never under @js-eyes/*. See docs/dev/js-eyes-skills/README.md for the full governance rule.

Terminology: JS Eyes Skills refers to the V2 skill.manifest.json/skill.entry.js contract and its supported V1 compatibility form. The skills/ namespace under docs/dev/ and examples/ is reserved for future compatibility with generic Skills specs (Anthropic Agent Skills, Cursor Skills, etc.). See docs/README.md for the full namespace map and site build layout.

Building

Prerequisites

Node.js >= 22
Run npm install in the project root
npm run build:firefox requires AMO_API_KEY and AMO_API_SECRET (for Mozilla signing). The repository now installs web-ext locally via npm install, so no separate global install is required.

Build Commands

# Build the distributable parent Skill bundle
npm run build:skill

# Build site (dist/) + skill bundles + skills.json registry
npm run build:site

# Build all unsigned, locally verifiable release artifacts
npm run build

# Build Chrome extension only
npm run build:chrome

# Build and sign Firefox extension
npm run build:firefox

# Bump platform version (excludes visual-* packages and skills/* sub-skills)
npm run bump -- 2.9.1

Output files are saved to the dist/ directory. The main skill bundle is staged under dist/skill-bundle/js-eyes/, published to dist/js-eyes-skill.zip, and versioned for releases as dist/js-eyes-skill-v<version>.zip.

The parent SKILL.md is rendered from distribution/js-eyes-skill/SKILL.template.md; the build injects the coordinated platform version. Repository coding-agent guidance lives separately in AGENTS.md.

For ClawHub publishing, use the generated bundle output (dist/skill-bundle/js-eyes/ or the versioned zip in dist/) as the source of truth instead of publishing from the monorepo root.

For the maintainer release checklist (develop -> main, npm CLI publish, GitHub Release, Firefox signed XPI, and AMO public submission), see RELEASE.md.

Repository releases use a read-only verification workflow followed by a manual, environment-gated publish workflow. npm publication uses GitHub OIDC trusted publishing; normal builds remain unsigned and do not consume release secrets.

Smoke Test

Use this checklist after a fresh ClawHub install:

cd ./skills/js-eyes && npm install
Confirm the resolved openclaw.json contains:
- plugins.load.paths -> absolute path to ./skills/js-eyes/openclaw-plugin
- plugins.entries["js-eyes"].enabled -> true
Restart or refresh OpenClaw
Run openclaw js-eyes status
Install the browser extension, connect it to http://localhost:18080, then run openclaw js-eyes tabs
Ask the agent to call js-eyes with action: browser/get-tabs
Ask the agent to call js-eyes with action: skills/discover
Install one child skill with action: skills/plan-install (or js-eyes skills link <path> for external skills). The main plugin hot-reloads within ~300 ms via the config watcher; confirm via action: skills/reload or the Hot-loaded skill / added entries in the gateway logs.

Troubleshooting

Symptom	Fix
Extension shows "Disconnected"	Check `openclaw js-eyes status`; ensure `autoStartServer` is `true`
`browser/get-tabs` returns empty	Click extension icon, verify address, click Connect
`Cannot find module 'ws'`	Run `npm install` in the skill root
Tools not appearing in OpenClaw	Ensure `plugins.load.paths` points to the main `openclaw-plugin` subdirectory and the target child skill is not disabled in the JS Eyes host config
Plugin path not found (Windows)	Use forward slashes in JSON, e.g. `C:/Users/you/skills/js-eyes/openclaw-plugin`
Agent returns `pending-egress` / policy-blocked text	The server policy engine blocked the URL or operation before it reached the browser. Run `js-eyes security show` to inspect `egressAllowlist` and `taskOrigin`; then use `js-eyes egress list`, `js-eyes egress approve <id>`, or `js-eyes egress allow <domain>` as appropriate. This is different from extension disconnects and consent gating.

Related Projects

OpenClaw — AI agent framework with extensible plugin system
DeepSeek Cowork — AI agent framework with full-featured browser automation support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Created by @imjszhang

Browser automation for any AI agent framework

js-eyes.com | GitHub | @imjszhang

Name		Name	Last commit message	Last commit date
Latest commit History 289 Commits
.github		.github
apps		apps
bin		bin
distribution/js-eyes-skill		distribution/js-eyes-skill
docs		docs
examples		examples
extensions		extensions
journal		journal
openclaw-plugin		openclaw-plugin
packages		packages
scripts		scripts
skills		skills
src		src
test		test
types		types
.clawhubignore		.clawhubignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
RELEASE_NOTES.md		RELEASE_NOTES.md
SECURITY.md		SECURITY.md
SECURITY_SCAN_NOTES.md		SECURITY_SCAN_NOTES.md
config.json		config.json
config.json.example		config.json.example
eslint.config.js		eslint.config.js
install.ps1		install.ps1
install.sh		install.sh
jsconfig.apps.json		jsconfig.apps.json
jsconfig.core.json		jsconfig.core.json
jsconfig.devtools.json		jsconfig.devtools.json
jsconfig.plugin.json		jsconfig.plugin.json
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

JS Eyes

Quick Install

Optional: Auto-sync token to browser extensions

Introduction

Monorepo Layout

Development

Supported Agent Frameworks

Native MCP Server

Features

Supported Browsers

Download

Manual Installation

Browser Extension

Chrome / Edge

Firefox

OpenClaw Skill Bundle

npm link Development Mode

Usage

1. Start a Compatible Server

2. Configure Connection

3. Verify Connection

4. Manage Skills from the CLI

Security Posture (2.10.0)

5. Security Quickstart (2.2.0+ / 2.3.0+)

CLI Runtime Directory

OpenClaw Plugin

What It Provides

Setup

Plugin Configuration

Compatibility Matrix

Extension Skills

Discovering Skills

Installing Extension Skills

Authoring your own JS Eyes Skill

Building

Prerequisites

Build Commands

Smoke Test

Troubleshooting

Related Projects

Contributing

License

Author

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages