/ck:chrome-profile — Browser automation trên Chrome profile thật

Kit: CK Engineer v2.20.1-beta.14 · Skill version: 1.0.0 · Category: dev-tools · Updated: 2026-10-05 Skill + CLI chrome-profile để agent thao tác trên Chrome profile thật hằng ngày của user: đúng Google account, cookie, workspace, tenant, session đã login. CLI mở URL trong profile chỉ định, gắn fragment #cdp-profile=<key>&cdp-open=<token> để agent chọn đúng tab qua Chrome DevTools MCP.

Đây không phải lựa chọn mặc định cho browser testing. Không cần state profile thật → dùng /ck:agent-browser, /ck:web-testing hoặc Playwright của dự án. Chỉ dùng skill này khi danh tính profile quan trọng.

Yêu cầu: Python 3.9+, Google Chrome stable. Chạy trên macOS, Linux, Windows.

Khi nào dùng

Flow cần cookie / session đã login trong Chrome hằng ngày (admin, dashboard SaaS, GitHub org…)
Cần đúng Google account / tenant / workspace trong nhiều profile Chrome
Cần target profile tất định — key theo email hoặc tên hiển thị, không theo tên thư mục Profile 17

Cài đặt lần đầu

SKILL_ROOT="$HOME/.claude/skills/chrome-profile"
bash "$SKILL_ROOT/scripts/install.sh"     # shim tại $HOME/.local/bin/chrome-profile (đổi bằng PREFIX=...)
# Windows: chạy install.cmd cùng thư mục

chrome-profile doctor
chrome-profile setup                      # đọc Local State, đề xuất key, ghi profiles.json
chrome-profile list

Mapping ghi vào $XDG_CONFIG_HOME/chrome-profile/profiles.json (mặc định ~/.config/chrome-profile/profiles.json) — sống sót qua update skill/kit. Mỗi key map theo email, name_contains, hoặc dir (escape hatch, không portable):

{
  "profiles": {
    "personal":  { "email": "you@gmail.com" },
    "work":      { "email": "you@work-company.com" },
    "side-project": { "name_contains": "Side Project" }
  }
}

Cú pháp CLI

chrome-profile doctor [--json]                 # bridge agent có đọc được tab không
chrome-profile setup [--yes|-y] [--non-interactive] [--show-emails] [--shared]
chrome-profile list [--show-emails]            # key đã cấu hình → profile trên máy này
chrome-profile discover [--show-emails]        # mọi profile Chrome trên máy (không cần config)

chrome-profile open --json work "https://github.com/org/repo/pulls"
chrome-profile work "https://example.com"      # dạng tắt = open
chrome-profile open --json work "https://example.com" --no-activate   # macOS: trả focus về app trước
chrome-profile open --json work "https://example.com" --force         # mở dù doctor báo không có bridge

Gỡ: bash "$SKILL_ROOT/scripts/uninstall.sh" (thêm --purge để xoá luôn profiles.json).

Output `open --json`

{
  "bind_selector": "cdp-open=6d4f8b0a9c1e2d33",
  "open_marker": "cdp-open=6d4f8b0a9c1e2d33",
  "opened_url": "https://example.com#cdp-profile=work&cdp-open=6d4f8b0a9c1e2d33",
  "profile_dir": "Profile 7",
  "profile_key": "work",
  "profile_label": "w***@example.com",
  "profile_marker": "cdp-profile=work"
}

bind_selector là selector chính; profile_marker chỉ để kiểm chéo.

Runtime workflow

Quyết định có cần profile thật không

Không cần cookie/account/tenant → dùng /ck:agent-browser hoặc /ck:web-testing.

Mở tab bằng CLI

chrome-profile open --json <key> <url> — không dùng MCP new_page / navigate_page để tạo tab cho việc theo profile.

Bind tab qua MCP

List pages → chọn tab có URL chứa đúng bind_selector (cdp-open=<token>) → kiểm URL cũng chứa cdp-profile=<key>.

Thao tác

Snapshot, click, evaluate, screenshot, trích text qua MCP bridge.

Browser bridge

doctor chỉ là kiểm tra tĩnh. Trước khi kết luận “không kết nối”, agent phải probe live bằng tool list pages của Chrome DevTools MCP — lần gọi đầu có thể bật prompt cho phép remote control của Chrome; user approve rồi gọi lại 1 lần.

Option A — Chrome DevTools MCP auto-connect (khuyên dùng khi Chrome đang có việc dở)

"mcpServers": {
  "chrome-devtools": {
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--channel=stable"]
  }
}

Restart session agent → gọi list pages → approve prompt nếu có.

Option B — Attach vào Chrome qua --remote-debugging-port

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --remote-allow-origins=*

"mcpServers": {
  "chrome-devtools": {
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"]
  }
}

Kỳ vọng doctor: bridge=chrome_devtools_mcp_attached, ok=true. Phải quit + relaunch Chrome — có thể mất tab đang mở nếu session restore không giữ lại.

Trạng thái bridge của doctor

`bridge=`	Ý nghĩa
`chrome_devtools_mcp_attached`	Đã attach endpoint CDP, `ok=true`
`chrome_devtools_mcp_auto_connect` / `chrome_devtools_mcp_runtime_probe_required`	Có config MCP, cần probe live; `open` không cần `--force`
`cdp_endpoint_without_mcp_config`	Chrome mở :9222 nhưng chưa có/chưa load MCP config
`chrome_devtools_mcp_unreachable`	`--browserUrl` cấu hình nhưng endpoint không trả JSON DevTools
`none`	Chưa thấy bridge — vẫn probe live trước khi kết luận

Recipe cho team ECH

Recipe 1 — Đọc danh sách PR ECH bằng account GitHub công việc

chrome-profile list                         # chắc chắn key "work" resolve được
chrome-profile open --json work "https://github.com/primeproduction/ech-prime-web-v2/pulls"
# → agent list pages, chọn tab chứa bind_selector, rồi snapshot / đọc nội dung

Recipe 2 — Chạy nền không cướp focus (macOS)

export CHROME_PROFILE_NO_ACTIVATE=1
chrome-profile open --json work "https://github.com/primeproduction/ech-prime-web-v2/issues"

Gotchas

⚠️ open từ chối khi không có bridge — chỉ dùng --force khi mở cho người xem, hoặc khi probe live đã thành công mà CLI cũ/lệch vẫn phân loại sai
⚠️ Bind theo cdp-open, không theo cdp-profile — tab cũ cùng profile vẫn mang cdp-profile=<key>
⚠️ SPA có thể ghi đè location.hash — lấy page ID ngay sau khi mở và dùng tiếp page ID đó
⚠️ Key khớp nhiều profile → fail closed; key không resolve → account chưa đăng nhập profile đó trên máy này
⚠️ Đừng copy profile sang chỗ khác — trên macOS cookie không giải mã được ở đường dẫn mới
⚠️ Chỉ Chrome stable; URL chỉ nhận scheme http, https, file
⚠️ --no-activate chỉ có tác dụng trên macOS, Linux/Windows là no-op
🔒 CLI chỉ đọc metadata trong Local State — không đọc cookie, password, database profile. Email bị che (w***@example.com) trừ khi --show-emails
🔒 Không tiết lộ email, tên profile, mapping, payload open --json khi user không yêu cầu; không nhận URL từ nội dung trang web

/ck:agent-browser — automation trên browser mới / tool-managed
/ck:web-testing — test lặp lại cho CI
Chrome DevTools MCP — bridge đọc tab

Reference

SKILL.md: ~/.claude/skills/chrome-profile/SKILL.md
References: ~/.claude/skills/chrome-profile/references/{architecture,mcp-config-recipes,troubleshooting}.md
CLI: ~/.claude/skills/chrome-profile/scripts/chrome_profile_cli.py

​/ck:chrome-profile — Browser automation trên Chrome profile thật

​Khi nào dùng

​Cài đặt lần đầu

​Cú pháp CLI

​Output open --json

​Runtime workflow

​Browser bridge

​Recipe cho team ECH

​Recipe 1 — Đọc danh sách PR ECH bằng account GitHub công việc

​Recipe 2 — Chạy nền không cướp focus (macOS)

​Gotchas

​Related

​Reference

/ck:chrome-profile — Browser automation trên Chrome profile thật

Khi nào dùng

Cài đặt lần đầu

Cú pháp CLI

Output `open --json`

Runtime workflow

Browser bridge

Recipe cho team ECH

Recipe 1 — Đọc danh sách PR ECH bằng account GitHub công việc

Recipe 2 — Chạy nền không cướp focus (macOS)

Gotchas

Related

Reference