browser-cdp

Q: How do I install browser-cdp?

Run npx skills add https://github.com/zenstory-ai/oh-story-claudecode --skill browser-cdp in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/browser-cdp/ (personal) or .claude/skills/browser-cdp/ (project).

by zenstory-aiProductivity & Automation

Use this skill when you need to control a Chrome browser via CDP (Chrome DevTools Protocol) to reuse existing login sessions. Covers: launching Chrome in debug mode, opening URLs, waiting for page load, evaluating JavaScript, taking snapshots, and extracting auth tokens. Trigger phrases: browser automation, CDP, agent-browser, 浏览器操作, 操作浏览器, Chrome CDP, 复用登录态, extract token from browser.

Installs: 16.9K
Last 24h: +98
Trending rank: #2012
Security: Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/zenstory-ai/oh-story-claudecode --skill browser-cdp

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads browser-cdp automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub WarnMEDIUM ·This skill provides browser automation capabilities by accessing local Chrome profiles to reuse login sessions. It possesses high-risk capabilities including the extraction of authentication tokens and direct access to sensitive browser data such as cookies and saved login information.

Socket Warn1 alert: gptAnomaly

Snyk WarnMEDIUM ·Risk: MEDIUM · 1 issue

SKILL.md

The instructions your agent reads when the skill is triggered.

Browser CDP 操作工具

通过 CDP（Chrome DevTools Protocol）连接 Chrome，复用登录态并执行浏览器操作。

前置条件

macOS / Linux / Windows（实验性），已安装并使用过 Google Chrome，来源 profile 已存在
Node.js 20+
agent-browser 已安装：npm install -g agent-browser

启动或重建时，若需结束 Chrome 进程，先按下方流程征得同意；未保存的标签页或草稿可能丢失。

启动流程（每次都按这个顺序）

下文 {SKILL_DIR} 指本 skill（browser-cdp）的目录。

第一步：探测当前状态（无副作用）

node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --detect-only

输出形如：

CDP_STATUS=ready                        # 已就绪，可直接复用
CDP_URL=http://127.0.0.1:9222/json/version
BROWSER=Chrome/148.0.7778.168

或：

CDP_STATUS=needs-setup
CHROME_RUNNING=yes                      # 用户有 Chrome 在跑，启动会杀掉
CHROME_PID_COUNT=3

第二步：根据探测结果分支

CDP_STATUS=needs-setup 且 CHROME_INSTALLED=no → 本机没找到 Chrome，告诉用户先安装并用它登录一次需要的网站，不要运行 setup。
CDP_STATUS=ready 且本次只需连接 → 直接使用 agent-browser --cdp 9222 ...，不要运行 setup。
明确请求 --reset / --profile → 即使 ready 也走重建，按下方「需要结束 Chrome 时」处理。
CDP_STATUS=needs-setup 且 CHROME_RUNNING=no → 安全启动：
```
node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --yes
```
CDP_STATUS=needs-setup 且 CHROME_RUNNING=yes → 按下方「需要结束 Chrome 时」处理。

需要结束 Chrome 时（同意流程）：凡是会结束正在运行的 Chrome 的命令（Chrome 在运行时启动、--reset、显式 --profile），都按这三步走：

带上原定选项加 --dry-run 跑一次，看会结束几个 Chrome 进程；
告诉用户会结束 N 个 Chrome 进程、未保存的标签页或草稿可能丢失，问是否继续；
用户同意后，去掉 --dry-run、加 --yes 重跑；用户拒绝就放弃这次自动化。

非 TTY 调用中，Chrome 在运行且未传 --yes 时，脚本以退出码 3 报 NEEDS_CONSENT: ... 并中止。取得同意后再重跑，不自动补 --yes。

换端口：9222 被别的程序占用时可以换一个端口（如 9333），之后所有 agent-browser --cdp 命令用同一个端口，扫榜脚本加 --port 9333，查资料助手传 cdp_port: 9333。

启动脚本选项

选项	说明
`--detect-only`	只探测，不修改任何状态
`--yes`	已征得同意，跳过交互提示
`--reset`	启动前清空 `~/chrome-debug-profile`（登录失效时用）
`--profile <name>`	指定来源 profile（默认 `Default`，如 `"Profile 1"`）；显式传入即重建
`--dry-run`	打印将执行的步骤，不执行

退出码：0 成功 / 1 通用错误 / 2 用户拒绝（TTY）/ 3 需同意但缺 --yes。

常用操作

打开页面并等待加载

agent-browser --cdp 9222 open "<URL>"
agent-browser --cdp 9222 wait 3000

提取页面文本

agent-browser --cdp 9222 eval 'document.body.innerText.substring(0, 8000)'

提取 Auth Token

示例读取 localStorage 的 token 项或 JavaScript 可读的 Cookie；实际存放位置按站点确认。

agent-browser --cdp 9222 eval 'localStorage.getItem("token") || document.cookie'

复杂 JS（含引号 / `$` / 反引号）

用 base64 或标准输入传入脚本，避免 shell 转义错误：

# 1) base64 包裹
agent-browser --cdp 9222 eval -b "$(echo -n "document.querySelectorAll('a').length" | base64)"

# 2) heredoc + --stdin
cat <<'EOF' | agent-browser --cdp 9222 eval --stdin
const links = document.querySelectorAll('a');
links.length;
EOF

页面交互（snapshot 拿元素引用）

agent-browser --cdp 9222 snapshot -i        # 仅交互元素
agent-browser --cdp 9222 click "<CSS or @e1>"
agent-browser --cdp 9222 type "<sel>" "<text>"

停止 / 清理

关掉 debug Chrome 窗口即可。若窗口无响应，先按 --user-data-dir 核验出 debug 实例的 PID 再只结束它：
- macOS / Linux：pgrep -af chrome-debug-profile
- Windows（PowerShell）：Get-CimInstance Win32_Process | Where-Object CommandLine -like '*chrome-debug-profile*' | Select-Object ProcessId,CommandLine；没有 PowerShell 的旧系统才用 wmic process get ProcessId,CommandLine | findstr chrome-debug-profile 核验 PID 后用 kill -9 {PID} / taskkill /F /PID {PID}，无法核验则停止。手工清理不得按 Chrome 可执行文件名批量结束进程；启动脚本仍走上述同意流程。
登录态失效：用 node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset 重新复制来源 profile，按上方「需要结束 Chrome 时」先 dry-run、征得同意再加 --yes。

长命令加超时

在前台执行耗时的 CDP 命令时，为页面加载和批量采集设置超时，避免单次调用长时间占住会话。

超时包装

Windows 用 PowerShell Job 设置超时：

$job = Start-Job { agent-browser --cdp 9222 eval "window.location.replace('https://www.qidian.com/rank/')" }
Wait-Job $job -Timeout 30 | Out-Null
if ($job.State -eq 'Running') { Stop-Job $job; Write-Output "⏱ CDP 操作超时（30s），请重试或手动打断" }
else { Receive-Job $job }
Remove-Job $job -Force

macOS / Linux 有 timeout 时：

timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.qidian.com/rank/')" || echo "⏱ CDP 操作超时（30s），请重试或手动打断"

已知限制

场景	风险	缓解
页面加载超时	eval 命令等待永不返回	设置 30s 超时，超时后重试
大批量数据抓取	多页翻页时累计等待过长	每页独立超时，失败后从断点继续
Chrome 进程僵死	CDP 连接断开但进程未退出	先核验 debug profile 对应 PID，只结束该 debug 实例后重连；不得连带普通 Chrome
网络波动	请求挂起无超时	超时后自动重试一次

持续卡死时，请用户在宿主里手动打断（如 OpenCode、Claude Code 按 ESC）。

常见问题

问题	解决方案
`NEEDS_CONSENT` + 退出码 3	按「需要结束 Chrome 时」：先 dry-run 说清会结束几个进程，同意后加 `--yes` 重跑
`CHROME_INSTALLED=no` 或来源 profile 不存在	安装并使用 Chrome 一次；已有其他 profile 时用 `--profile` 指定（会重建，按同意流程）
CDP 端口未监听	`--detect-only` 再确认；端口被占用就换端口，下游命令一起改（见「换端口」）
页面跳转到登录页	`snapshot -i` 找登录按钮并操作
`eval` 返回 `null`	检查 localStorage key 名；含引号的 JS 用 `eval -b` 或 `--stdin`
登录态过期	`setup-cdp-chrome.js 9222 --reset`，按同意流程先 dry-run、同意后加 `--yes`
有多个 Chrome profile	`--profile "Profile 1"` 指定；显式传 `--profile` 会重建，按同意流程
Chrome 不会启动（30s 超时）	检查端口冲突；查看 `~/chrome-debug-profile/` 是否损坏；仍不行再按同意流程试 `--reset`

FAQ

What does the browser-cdp skill do?

How do I install browser-cdp?

Run npx skills add https://github.com/zenstory-ai/oh-story-claudecode --skill browser-cdp in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/browser-cdp/ (personal) or .claude/skills/browser-cdp/ (project).

Which AI agents can use browser-cdp?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is browser-cdp safe to install?

Security partners have reviewed it: Gen Agent Trust Hub flagged items to review; Socket flagged items to review; Snyk flagged items to review. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains browser-cdp?

It is published by zenstory-ai in zenstory-ai/oh-story-claudecode. It has 16,884 recorded installs.