# Browser CDP Control

Controls Chrome over DevTools Protocol to reuse login sessions and tokens.

- Repository: https://github.com/zenstory-ai/oh-story-claudecode (8225 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add zenstory-ai/oh-story-claudecode --skill browser-cdp -g -a claude-code -y`
Codex: `npx skills add zenstory-ai/oh-story-claudecode --skill browser-cdp -g -a codex -y`
Cursor: `npx skills add zenstory-ai/oh-story-claudecode --skill browser-cdp -g -a cursor -y`
Gemini CLI: `npx skills add zenstory-ai/oh-story-claudecode --skill browser-cdp -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add zenstory-ai/oh-story-claudecode`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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）的目录。

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

```bash
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` → 安全启动：
  ```bash
  node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --yes
  ```
- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=yes` → 按下方「需要结束 Chrome 时」处理。

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

1. 带上原定选项加 `--dry-run` 跑一次，看会结束几个 Chrome 进程；
2. 告诉用户会结束 N 个 Chrome 进程、未保存的标签页或草稿可能丢失，问是否继续；
3. 用户同意后，去掉 `--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`。

---

## 常用操作

### 打开页面并等待加载

The rest: https://github.com/zenstory-ai/oh-story-claudecode/blob/HEAD/skills/browser-cdp/SKILL.md