Back to Details

agent-browser-local

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Local Browser Automation with agent-browser + Comet CDP

基于agent-browser + Comet CDP的本地浏览器自动化

This skill connects agent-browser to the user's real local Comet browser via Chrome DevTools Protocol (CDP). This gives you access to the user's actual browser profile — cookies, login sessions, extensions, and all.
本技能通过Chrome DevTools Protocol（CDP）将agent-browser连接到用户本地的真实Comet浏览器，让你能够访问用户实际的浏览器配置文件——包括Cookie、登录会话、扩展程序等所有内容。

Setup: Launch Browser with CDP

设置：通过CDP启动浏览器

Before any browser commands, you must ensure Comet is running with CDP enabled. Do this ONCE per session, then reuse for all subsequent commands.
在执行任何浏览器命令之前，你必须确保Comet已启用CDP运行。每个会话只需执行一次此操作，之后所有后续命令均可复用该会话。

Headed Mode (default — visible browser window)

有界面模式（默认——可见浏览器窗口）

bash
undefined
bash
undefined

Kill any existing Comet to avoid "Opening in existing session" conflicts

Kill any existing Comet to avoid "Opening in existing session" conflicts

pkill -9 -f Comet 2>/dev/null; sleep 2
pkill -9 -f Comet 2>/dev/null; sleep 2

Launch with CDP

Launch with CDP

/Applications/Comet.app/Contents/MacOS/Comet --remote-debugging-port=${COMET_CDP_PORT:-9222} &disown 2>/dev/null sleep 3
/Applications/Comet.app/Contents/MacOS/Comet --remote-debugging-port=${COMET_CDP_PORT:-9222} &disown 2>/dev/null sleep 3

Verify CDP is ready

Verify CDP is ready

curl -s http://localhost:${COMET_CDP_PORT:-9222}/json/version >/dev/null && echo "CDP ready"
curl -s http://localhost:${COMET_CDP_PORT:-9222}/json/version >/dev/null && echo "CDP ready"

Bring window to foreground

Bring window to foreground

osascript -e 'tell application "Comet" to activate'
undefined
osascript -e 'tell application "Comet" to activate'
undefined

Headless Mode (no visible window, still uses real profile)

无头模式（无可见窗口，仍使用真实配置文件）

bash
pkill -9 -f Comet 2>/dev/null; sleep 2

/Applications/Comet.app/Contents/MacOS/Comet --headless=new --remote-debugging-port=${COMET_CDP_PORT:-9222} &disown 2>/dev/null
sleep 3

curl -s http://localhost:${COMET_CDP_PORT:-9222}/json/version >/dev/null && echo "CDP ready"
bash
pkill -9 -f Comet 2>/dev/null; sleep 2

/Applications/Comet.app/Contents/MacOS/Comet --headless=new --remote-debugging-port=${COMET_CDP_PORT:-9222} &disown 2>/dev/null
sleep 3

curl -s http://localhost:${COMET_CDP_PORT:-9222}/json/version >/dev/null && echo "CDP ready"

Check if Already Running

检查是否已在运行

Before launching, check if Comet CDP is already available from a previous command in this session:
bash
curl -s http://localhost:${COMET_CDP_PORT:-9222}/json/version >/dev/null 2>&1 && echo "ALREADY RUNNING" || echo "NEED TO LAUNCH"
If already running, skip the launch step entirely. This is critical for session reuse.
启动前，检查当前会话中是否已有之前的命令启动了Comet CDP：
bash
curl -s http://localhost:${COMET_CDP_PORT:-9222}/json/version >/dev/null 2>&1 && echo "ALREADY RUNNING" || echo "NEED TO LAUNCH"
如果已在运行，请完全跳过启动步骤。这对于会话复用至关重要。

Core Rule: Always Pass 
--cdp

核心规则：始终传递
--cdp
参数

Every 
agent-browser
command MUST include 
--cdp ${COMET_CDP_PORT:-9222}
. This connects to the local Comet instance instead of launching a new browser.
bash
undefined
每个
agent-browser
命令都必须包含
--cdp ${COMET_CDP_PORT:-9222}
，这样才能连接到本地Comet实例，而非启动新的浏览器。
bash
undefined

CORRECT — uses local Comet

正确用法 —— 使用本地Comet

agent-browser --cdp ${COMET_CDP_PORT:-9222} open https://example.com agent-browser --cdp ${COMET_CDP_PORT:-9222} snapshot -i agent-browser --cdp ${COMET_CDP_PORT:-9222} click @e1
agent-browser --cdp ${COMET_CDP_PORT:-9222} open https://example.com agent-browser --cdp ${COMET_CDP_PORT:-9222} snapshot -i agent-browser --cdp ${COMET_CDP_PORT:-9222} click @e1

WRONG — would launch isolated headless browser, losing auth

错误用法 —— 会启动隔离的无头浏览器，丢失身份验证信息

agent-browser open https://example.com
undefined
agent-browser open https://example.com
undefined

Workflow

工作流程

Every interaction follows this pattern:
  1. Ensure CDP is running (check first, launch only if needed)
  2. Navigate: 
    agent-browser --cdp 9222 open <url>
  3. Snapshot: 
    agent-browser --cdp 9222 snapshot -i
    (get element refs like 
    @e1
    , 
    @e2
    )
  4. Interact: Use refs to click, fill, select — always with 
    --cdp 9222
  5. Re-snapshot: After navigation or DOM changes, get fresh refs
bash
undefined
所有交互都遵循以下模式：
  1. 确保CDP正在运行（先检查，仅在需要时启动）
  2. 导航：
    agent-browser --cdp 9222 open <url>
  3. 快照：
    agent-browser --cdp 9222 snapshot -i
    （获取元素引用，如
    @e1
    、
    @e2
    ）
  4. 交互：使用元素引用执行点击、填充、选择等操作——始终携带
    --cdp 9222
    参数
  5. 重新快照：导航或DOM变更后，获取新的元素引用
bash
undefined

Check CDP

检查CDP状态

curl -s http://localhost:9222/json/version >/dev/null 2>&1 || { echo "Launch Comet first"; exit 1; }
curl -s http://localhost:9222/json/version >/dev/null 2>&1 || { echo "Launch Comet first"; exit 1; }

Navigate and interact

导航并交互

agent-browser --cdp 9222 open https://example.com/dashboard agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 open https://example.com/dashboard agent-browser --cdp 9222 snapshot -i

Output: @e1 [button] "Settings", @e2 [link] "Profile", ...

输出：@e1 [button] "Settings", @e2 [link] "Profile", ...

agent-browser --cdp 9222 click @e2 agent-browser --cdp 9222 snapshot -i # Fresh refs after navigation
undefined
agent-browser --cdp 9222 click @e2 agent-browser --cdp 9222 snapshot -i # 导航后获取新的元素引用
undefined

Command Chaining

命令链式调用

Commands can be chained with 
&&
. Always include 
--cdp
on each:
bash
agent-browser --cdp 9222 open https://example.com && agent-browser --cdp 9222 wait --load networkidle && agent-browser --cdp 9222 snapshot -i
命令可以通过
&&
进行链式调用，每个命令都必须包含
--cdp
参数：
bash
agent-browser --cdp 9222 open https://example.com && agent-browser --cdp 9222 wait --load networkidle && agent-browser --cdp 9222 snapshot -i

Essential Commands

常用命令

All standard agent-browser commands work — just prepend 
--cdp 9222
:
bash
undefined
所有标准的agent-browser命令都可使用——只需添加
--cdp 9222
前缀：
bash
undefined

Navigation

导航相关

agent-browser --cdp 9222 open <url> agent-browser --cdp 9222 close # Disconnects agent-browser (does NOT close Comet)
agent-browser --cdp 9222 open <url> agent-browser --cdp 9222 close # 断开agent-browser连接（不会关闭Comet）

Snapshot & Interaction

快照与交互

agent-browser --cdp 9222 snapshot -i agent-browser --cdp 9222 click @e1 agent-browser --cdp 9222 fill @e2 "text" agent-browser --cdp 9222 select @e3 "option" agent-browser --cdp 9222 press Enter agent-browser --cdp 9222 scroll down 500
agent-browser --cdp 9222 snapshot -i agent-browser --cdp 9222 click @e1 agent-browser --cdp 9222 fill @e2 "text" agent-browser --cdp 9222 select @e3 "option" agent-browser --cdp 9222 press Enter agent-browser --cdp 9222 scroll down 500

Information

信息获取

agent-browser --cdp 9222 get text @e1 agent-browser --cdp 9222 get url agent-browser --cdp 9222 get title
agent-browser --cdp 9222 get text @e1 agent-browser --cdp 9222 get url agent-browser --cdp 9222 get title

Wait

等待操作

agent-browser --cdp 9222 wait @e1 agent-browser --cdp 9222 wait --load networkidle
agent-browser --cdp 9222 wait @e1 agent-browser --cdp 9222 wait --load networkidle

Capture

捕获操作

agent-browser --cdp 9222 screenshot agent-browser --cdp 9222 screenshot --full agent-browser --cdp 9222 screenshot --annotate
undefined
agent-browser --cdp 9222 screenshot agent-browser --cdp 9222 screenshot --full agent-browser --cdp 9222 screenshot --annotate
undefined

User Preferences

用户偏好设置

Ask the user on first invocation:
  • Headed or headless? Default to headed so the user can see what's happening.
  • If the user says "headed", bring Comet to the foreground with 
    osascript -e 'tell application "Comet" to activate'
    after launch.
首次调用时询问用户：
  • 使用有界面还是无头模式？ 默认使用有界面模式，以便用户可以查看操作过程。
  • 如果用户选择“有界面”，启动后通过
    osascript -e 'tell application "Comet" to activate'
    将Comet窗口前置。

Session Lifecycle

会话生命周期

  • Launch once: The browser persists for the entire Claude Code session
  • Reuse always: Check CDP before every interaction, never re-launch if already running
  • Don't kill on "close": 
    agent-browser --cdp 9222 close
    only disconnects agent-browser's Playwright session from the CDP endpoint. It does NOT close or kill Comet. The user's browser stays open.
  • No cleanup needed: When the Claude Code session ends, Comet keeps running as the user's normal browser
  • 仅启动一次：浏览器在整个Claude Code会话期间保持运行
  • 始终复用：每次交互前检查CDP状态，若已运行则绝不重新启动
  • “关闭”操作不终止浏览器：
    agent-browser --cdp 9222 close
    仅断开agent-browser的Playwright会话与CDP端点的连接，不会关闭或终止Comet。用户的浏览器将保持打开状态。
  • 无需清理：当Claude Code会话结束时，Comet将继续作为用户的常规浏览器运行

Configuration

配置项

VariableDefaultDescription
COMET_CDP_PORT
9222
CDP port for remote debugging
变量默认值描述
COMET_CDP_PORT
9222
用于远程调试的CDP端口

Troubleshooting

故障排除

"Opening in existing browser session"

“Opening in existing browser session”（在现有浏览器会话中打开）

Comet was already running without CDP. Kill it first, then relaunch with 
--remote-debugging-port
:
bash
pkill -9 -f Comet 2>/dev/null; sleep 2
/Applications/Comet.app/Contents/MacOS/Comet --remote-debugging-port=9222 &disown
Comet已在未启用CDP的情况下运行。先终止它，再重新启动并添加
--remote-debugging-port
参数：
bash
pkill -9 -f Comet 2>/dev/null; sleep 2
/Applications/Comet.app/Contents/MacOS/Comet --remote-debugging-port=9222 &disown

CDP not responding

CDP无响应

Wait longer — some systems need 3-5 seconds for Comet to start:
bash
for i in {1..10}; do curl -s http://localhost:9222/json/version >/dev/null 2>&1 && break; sleep 1; done
等待更长时间——部分系统需要3-5秒让Comet启动：
bash
for i in {1..10}; do curl -s http://localhost:9222/json/version >/dev/null 2>&1 && break; sleep 1; done

Port already in use

端口已被占用

Another process is using port 9222. Either kill it or use a different port:
bash
COMET_CDP_PORT=9333 agent-browser --cdp 9333 open https://example.com
其他进程正在使用9222端口。可以终止该进程或使用其他端口：
bash
COMET_CDP_PORT=9333 agent-browser --cdp 9333 open https://example.com