browserclaw

name	browserclaw
description	Use the browserclaw CLI to capture browser traffic, infer API endpoints, generate Python clients, OR decrypt + inject Chrome cookies for session reuse. Use when asked to reverse-engineer a website, generate an API client from a HAR, or reuse a logged-in Chrome session in a Playwright browser.
agent_scope	Any AI agent (Codex, Claude Code, Hermes, AO)

browserclaw

What this skill covers

The browserclaw CLI (a single Python binary installed via pip install -e .) has two halves:

1. Traffic capture + client generation — record a Chromium session to a HAR, infer the API endpoints, emit a requests-based Python client + MCP tool definitions.
2. Cookie decrypt + inject (introduced in PR #6) — read the user's logged-in cookies out of the local Chrome/Brave/Edge SQLite DB, decrypt the AES-128 ciphertext using the macOS Keychain password, and inject them into a fresh Playwright Chrome so an agent can act as that user without re-authenticating.

This file documents the cookies subcommands. The capture / infer / generate flow is documented in ~/.claude/skills/browserclaw/SKILL.md (legacy) and the upstream browserclaw/SKILL.md.

⚡ AUTH-GATED SHARE LINK — FIRE THIS ON FIRST REFUSAL (added 2026-07-20)

Trigger (read this BEFORE running any anonymous fetch): the user asks you to read / save / summarize / extract / ingest / archive / make a PR from the content of an auth-gated share link — share.gemini.google/..., chatgpt.com/share/..., docs.google.com/document/d/.../edit (restricted), notion.so/... shared page, vendor AI share dialog — AND an anonymous fetch (curl, web_extract, browser_navigate with no cookies) returns the vendor's sign-in shell with the content loaded client-side only after auth.

Action (do NOT post an unblock menu, do NOT ask the user to paste the content):

1. Run browserclaw cookies decrypt on the user's Chrome Default profile (or sweep Profile 1 / Profile 2 / Aside / Brave / Edge if 0 cookies — see references/multi-profile-cookie-scan.md).
2. Run browserclaw cookies inject with --browser-channel chromium --headless --wait-after-load 12 --print-text 100000 to dump the page text.
3. If --print-text truncates mid-sentence (Gemini share pages lazy-load), re-extract via Playwright + scroll-to-bottom with the same cookies.
4. Verify the page loaded as the user (expected first-user message in the dump, NOT the vendor sign-in form). Then proceed with the user's actual ask against the captured content.

The 5-step recipe is verified end-to-end at references/gemini-share-link-as-user.md (Gemini share Td7fA4pzuvMs, 2026-07-20, 79 Google cookies decrypted, 169KB page text extracted, campaign module saved via PR $GITHUB_REPOSITORY#8483). The full session analysis — including the user's verbatim correction — is at references/gemini-share-link-stopping-pattern.md.

Why this rule exists: posting a 4-option unblock menu ("paste the content / re-share publicly / Doc export / proceed from title alone") on first refusal was the failure mode the user explicitly corrected in Slack thread C0AH3RY3DK6/p1784580748.125749 (verbatim: "use /browser or /browserclaw headless next time without asking"). Doing the recipe costs ~5 seconds of browserclaw time; asking the user costs them a full reply round-trip and breaks their flow. Bias toward running the recipe.

Companion contract test: tests/test_browser_command_mentions_browserclaw.py in ~/jleechanclaw (PR jleechanorg/jleechanclaw#788) fails if ~/.claude/commands/browser.md drops the browserclaw reference or the auth-gate recipe pointer. SOUL.md ## COMMIT: read-auth-gated-share-links-with-browserclaw (53rd COMMIT, added 2026-07-20) is the trigger-based contract that enforces this on every session. The contract test + the SOUL.md COMMIT + this SKILL.md section are the three layers of the durable fix.

When to use cookies decrypt + cookies inject

Use this pair when:

• The site is behind a login that requires MFA / SSO / WebAuthn (programmatic re-auth is impractical).
• The user has Chrome open and already logged into the target site.
• You need a Playwright session that appears as the user — same cookies, same session, same auth tokens.
• A token rotation / invalid_auth incident requires you to read what cookies Chrome currently has so you can decide whether to re-decrypt or escalate.
• The user asks you to "read" or "save" content from an auth-gated share link (Gemini share https://share.gemini.google/…, ChatGPT shared conversation https://chatgpt.com/share/…, Google Doc with restricted access, Notion shared page, etc.) and the page returns a sign-in shell when fetched anonymously. Don't ask the user to paste the content — reach for this pair on the first refusal and read the page as them, headless. Verified recipe at references/gemini-share-link-as-user.md.

Do not use this for:

• Sites you do not have permission to access. The skill trusts the user's local keychain; if you are not the user, this is unauthorized access.
• Bypassing 2FA, CAPTCHAs, or anti-bot protections. The skill reuses an existing logged-in session — it does not break new ones.
• Linux/Windows browsers. The PBKDF2 + Keychain parameters are macOS-only (salt saltysalt, iterations 1003, IV = 16 spaces). Linux Chromium uses peanuts / 1 iteration and is not supported by this CLI yet.

Prerequisites

# From a checked-out browserclaw worktree or installed wheel
pip install -e '.[dev]'
python -m playwright install chromium
# cryptography>=42.0.0 is the only new dep introduced by PR #6

• macOS only (uses security find-generic-password against the Login keychain).
• Chrome (default) or Brave / Edge with explicit --keychain-service / --keychain-account flags.
• The user must have already logged into the target site in Chrome at least once (the SQLite Cookies DB must contain the encrypted values).
• Chrome must have been closed OR the file must be readable — the CLI copies the DB to a temp file before opening, so live read is safe even while Chrome is running, but a value that exists only in Chrome's in-memory cache may not yet be flushed to disk.

Subcommand: browserclaw cookies decrypt

Read the local Chrome Cookies SQLite DB, decrypt every cookie value with the Keychain-derived AES key, and write a Playwright-compatible JSON.

Synopsis

browserclaw cookies decrypt \
  --db ~/Library/Application\ Support/Google/Chrome/Default/Cookies \
  --output ./cookies.json \
  [--domain-filter '%slack.com%'] \
  [--keychain-service 'Chrome Safe Storage'] \
  [--keychain-account 'Chrome'] \
  [--summary]

Arguments

Flag	Type	Default	Required	Purpose
--db	path	—	yes	Absolute path to the Chromium-format Cookies SQLite. The CLI copies it to a temp file before opening, so passing the live Chrome-locked path is safe.
--output, -o	path	—	yes	Destination for the decrypted JSON (Playwright storage_state shape: {"cookies": [...], "origins": []}).
--domain-filter	str	%	no	SQL LIKE pattern against host_key. Use %slack.com% to grab only Slack cookies, %.google.com% to grab all subdomains.
--keychain-service	str	Chrome Safe Storage	no	Override for Brave (Brave Safe Storage) or Edge (Microsoft Edge Safe Storage).
--keychain-account	str	Chrome	no	Override for Brave (Brave) or Edge (Microsoft Edge).
--summary	flag	off	no	Print a one-line domain name len=N per cookie instead of full values. Use when debugging to avoid logging tokens.

Outputs

• Writes --output as a Playwright storage_state JSON: {"cookies": [{"name","value","domain","path","expires","secure","httpOnly","sameSite"}, ...], "origins": []}.
• Prints either the JSON summary (default) or the per-cookie summary lines (--summary).
• Exit code 0 on success, non-zero on CookieDecryptError (missing DB, empty file, no meta.version row, Keychain lookup failure).

Example — extract Slack cookies for an agent run

browserclaw cookies decrypt \
  --db ~/Library/Application\ Support/Google/Chrome/Default/Cookies \
  --output /tmp/slack-cookies.json \
  --domain-filter '%slack.com%' \
  --summary
# Wrote 26 cookies to /tmp/slack-cookies.json
#   .slack.com                          d                     len=  225
#   .slack.com                          d-s                   len=   35
#   .slack.com                          b                     len=   18
#   .slack.com                          lc                    len=   31
#   .slack.com                          oi                    len=   17

Example — Brave browser

browserclaw cookies decrypt \
  --db ~/Library/Application\ Support/BraveSoftware/Brave-Browser/Default/Cookies \
  --output /tmp/brave-cookies.json \
  --keychain-service 'Brave Safe Storage' \
  --keychain-account 'Brave'

Example — Aside browser (2026-06-27, primary browser)

Aside uses the same Chromium v24 cookie schema but its own Keychain entry (Aside Safe Storage). The DB path is ~/Library/Application Support/Aside/Default/Cookies.

browserclaw cookies decrypt \
  --db ~/Library/Application Support/Aside/Default/Cookies \
  --output /tmp/aside-cookies.json \
  --keychain-service 'Aside Safe Storage' \
  --keychain-account 'Aside'

Keychain prerequisite: the Aside Safe Storage entry is only created after Aside writes its first cookie to disk. If you see Keychain lookup failed for service='Aside Safe Storage' account='Aside', log into a site in Aside once (any login), then re-run. Verify the entry exists:

security find-generic-password -s 'Aside Safe Storage' -a 'Aside' -w

Cross-browser portability warning: the underlying PBKDF2 password is per-browser (each browser has its own Keychain entry). Even after cookies decrypt succeeds, cookies decrypted from Aside cannot be replayed into a Chrome session and vice versa without re-encryption under the target's password — browserclaw does NOT do this re-encryption. Use the cookies decrypt + cookies inject cycle only on the same browser that produced the cookies.

Aside cookies decrypt but Slack auth rejects them (verified 2026-07-19, mcp_agent_mail OAuth fix): Aside's d cookie decrypts to a hex string (Slack's newer encrypted cookie format) rather than the legacy xoxd-... URL-encoded format Chrome uses. Direct auth.test against the Aside-decrypted cookies returns {"ok":false,"error":"not_authed"} — the values are well-formed but Slack's session validation doesn't accept the newer format. For Slack targets specifically, prefer Chrome Default cookies over Aside cookies. Verified end-to-end: decrypting Chrome Default's d (legacy xoxd-...) and feeding that into cookies inject → Playwright session authenticated to https://app.slack.com/app-settings/... as the user.

Edge cases / failure modes

Symptom	Likely cause	Fix
CookieDecryptError: Cookie DB not found	Wrong path or the browser is not installed	Confirm path with ls "$HOME/Library/Application Support/Google/Chrome/Default/Cookies"
CookieDecryptError: Cookie DB is empty	Chrome is currently writing to it; live copy is zero bytes	Quit Chrome fully, then re-run
CookieDecryptError: is not a Chromium Cookies DB (no meta.version row)	Wrong file — it's not a Chromium Cookies SQLite	Check --db is a Cookies file, not Cookies-journal or Login Data
Keychain lookup failed for service='Chrome Safe Storage' account='Chrome'	User clicked "Deny" on the keychain prompt, or the entry was removed	Open Keychain Access.app, search for Chrome Safe Storage, ensure it exists; re-run and click "Always Allow"
Output JSON has 0 cookies	--domain-filter is too narrow, or the user is not logged into that site in this profile	Drop --domain-filter to %, or switch --db to the correct profile (Profile 1, Profile 2, …)
Output JSON has N>0 cookies but every value is "" (length fields populated)	Chrome v120+ App-Bound Encryption (v20 prefix) — Safe Storage decrypt is necessary but no longer sufficient; cookies.py only handles v10/v11	Use the v20 bypass recipe in references/cdp-decrypt-via-headless-browser.md — launch headless Chrome with --remote-debugging-port, call CDP Network.getAllCookies, Chrome decrypts v20 in-process. Verified 2026-07-18.
browserclaw --help returns empty / ModuleNotFoundError: No module named 'browserclaw.cli' (verified 2026-07-11)	Editable install's source worktree was deleted but the .pth still points to it. pip show browserclaw shows Editable project location: <some-path>; that directory no longer exists

Subcommand: browserclaw cookies inject

Open a Playwright Chrome (or chromium), inject the cookies from a previously-decrypted JSON, navigate to a target URL, and optionally screenshot / dump page text.

Synopsis

browserclaw cookies inject \
  --cookies ./cookies.json \
  --goto https://app.slack.com/client \
  [--browser-channel chrome] \
  [--headless] \
  [--wait-after-load 5] \
  [--screenshot /tmp/slack-home.png] \
  [--print-text 500]

Arguments

Flag	Type	Default	Required	Purpose
--cookies	path	—	yes	Path to a cookies JSON. Either the output of cookies decrypt or any Playwright storage_state file.
--goto	URL	—	yes	Where to navigate after injection. Must be a URL whose domain matches the cookies (cookies are domain-scoped).
--browser-channel	str	chrome	no	Playwright channel. Use chrome for the real installed Chrome, chromium for the headless test build, msedge for Edge.
--headless	flag	off	no	Run without a visible window. Combine with --screenshot for evidence capture.
--wait-after-load	float	5.0	no	Seconds to wait after page.goto returns, before printing diagnostics. Increase for SPAs that hydrate slowly.
--screenshot	path	off	no	If set, save a full-page screenshot after navigation. Great for evidence + Slack thread attachments.
--print-text	int	0	no	If > 0, print the first N characters of document.body.innerText after navigation. Useful for verifying the page loaded as the expected user.

Outputs

• Opens (or spawns) a real browser window — visible by default unless --headless.
• Prints the final URL, page title, and any --print-text content to stdout.
• Writes screenshot to --screenshot path if provided.
• Exit code 0 on successful navigation; non-zero if Playwright cannot launch, cookies JSON is empty, or page.goto errors.

Example — drive Slack web as the user

browserclaw cookies inject \
  --cookies /tmp/slack-cookies.json \
  --goto https://app.slack.com/client \
  --browser-channel chrome \
  --wait-after-load 5 \
  --print-text 800 \
  --screenshot /tmp/slack-home.png

Example — headless evidence capture

browserclaw cookies inject \
  --cookies /tmp/slack-cookies.json \
  --goto https://app.slack.com/client \
  --browser-channel chromium \
  --headless \
  --wait-after-load 3 \
  --screenshot ./evidence/slack-after-login.png

Edge cases / failure modes

Symptom	Likely cause	Fix
No cookies found in <path>	JSON is empty or has no cookies key	Re-run cookies decrypt and confirm the file has {"cookies": [...]}
Navigation lands on login page despite valid cookies	Domain mismatch — --goto is on a domain that does not match the cookie's host_key	Use a URL whose host matches at least one cookie domain
Navigation lands on login page despite valid cookies AND correct domain	Browser fingerprinting — site rejects Playwright-launched Chrome even with valid session cookies (LinkedIn, Twitter/X, Threads, Facebook, Dev.to observed 2026-07-05). The cookies are accepted by the HTTP layer but the site's JS anti-bot detects the Playwright Chrome fingerprint and redirects. browserclaw cookies inject is NOT a universal login bypass — it only works on sites that don't fingerprint-auth the session.	(1) Check if the site works in a normal Chrome tab with the same cookies (yes → fingerprint issue). (2) Try --browser-channel chromium instead of chrome (different fingerprint, sometimes passes). (3) For sites that always reject Playwright, use aside repl instead — Aside's persistent daemon has a real Chrome fingerprint and may pass. (4) If all fail, the user must log in manually in the target browser first, then re-decrypt.
channel='chrome' opens a visible Chrome window during launch even with --headless flag (verified 2026-07-18, multi-portal tax drive)	Playwright's channel='chrome' spawns the system Chrome binary which has different headless-launch behavior than bundled Chromium-for-Testing — it briefly opens a visible window before transitioning to headless, AND the user's existing Chrome session can gain new tabs that pollute their work. This is the user's #1 complaint ("use headless browser, stop doing normal browser", "use headless chrome, it keeps opening up").	Default: --browser-channel chromium (the bundled Chromium-for-Testing) — it's always headless and never opens a visible window, even though its TLS fingerprint fails more bot-detection checks. Only fall back to channel='chrome' when (a) the user has explicitly opted in ("show browser" / "headed mode" / "I want to see the window") AND (b) the target site blocks bundled Chromium's fingerprint. If is unavoidable, use AND verify with and that no new visible window appeared.

Poll-until-cookies-appear pattern

When the browserclaw prerequisite is not yet met (user has never visited the target SPA in their browser, so the cookies-to-decrypt don't exist yet), do NOT just stop and ask the user to "go log in manually." Instead, register a recurring hermes cron that polls for the cookies and automatically drives the headless repro the moment they appear.

Verified worked example (2026-07-12, your-project.com SPA, campaign a1OGXHNxNdw1Id0iRfpR):

The user said "use /browserclaw to log in as me and get the repro." They had 81 valid *.google.com cookies but ZERO worldarchitecture-ai cookies. After confirming they hadn't visited the SPA in Chrome, I registered a recurring 5-min poll:

hermes cron create \
  --name "wa-cookies-poll #8353 (5m) recurring" \
  --schedule "every 5m" \
  --repeat 99999 \
  --deliver "slack:<channel-id>:<thread-ts>" \
  --model MiniMax-M3 --provider minimax \
  --prompt '<see template below>'

The cron prompt (template — fill in the campaign-specific context for your run):

You are a polling watcher for the <SPA_NAME> post-auth repro.

EVERY tick:
1. env -i HOME="$HOME" PATH="$HOME/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" \
     "$(which browserclaw)" cookies decrypt \
     --db "$HOME/Library/Application Support/Google/Chrome/Default/Cookies" \
     --output /tmp/wa-cookies.json \
     --domain-filter '%<SPA_DOMAIN>%' --summary 2>&1 | head -10

2. If output starts with "Wrote 0 cookies":
   - If this is tick #4, #8, #12, ... (every ~20m) → post ONE line: ":hourglass: still polling for <SPA_DOMAIN> cookies (tick N)"
   - Else → EXIT SILENTLY
   - If total ticks > 24 (~2h) without cookies appearing → post "polling timed out after 2h" then `cronjob action=remove job_id=$CRON_JOB_ID`. EXIT.

3. If output starts with "Wrote N cookies" (N>0) → COOKIES APPEARED:
   a. Sanity check: `python3 -c "import json; d=json.load(open('/tmp/wa-cookies.json')); print(len(d.get('cookies',[])))"`
   b. Modify /tmp/repro-<id>/probe_with_real_session.py to point at wa-cookies.json instead of google-cookies.json.
   c. Run it with --browser-channel chromium --headless; capture screenshot, DOM probe, console, network failures.
   d. For each candidate campaign id (the user's reported one + any sibling-affected ones), navigate separately and capture symptom.
   e. POST result in this Slack thread:
      ```
      :unlock: /repro post-auth captured!
      - <SPA_DOMAIN> cookies: N present
      - Campaign <CID_1>: [loaded | 500 stuck | other symptom text]
      - Evidence: /tmp/repro-<id>/post_auth_*.{png,txt}
      - Verdict: REPRO | RELATED | NON-REPRO per /repro §4
      ```
   f. Append evidence to the GitHub issue (`gh issue comment <N> --body-file ...` using env -i wrapper).
   g. CRON SELF-CANCEL: `hermes cron remove $CRON_JOB_ID` (NOT `cronjob action=remove` — that CLI was renamed in 2026-07-13; `cronjob` is no longer on PATH and the old form fails with `FileNotFoundError`). See babysit-ao-pr-loop v1.3.1 changelog.

**How to determine your tick number N** (the "tick #4 / #8 / #12 ..." gate above):

The cron prompt is told to post hourglass updates at every 4th tick (~20 min), but does NOT know its own tick count. Three reliable ways to derive it, in order of preference:

1. **`jobs.json` counters** (authoritative — read at the top of every tick):
   ```bash
   JOB_ID="<your cron job id — usually $CRON_JOB_ID from launchd env>"
   python3 -c "
   import json, datetime
   d = json.load(open('$HOME/.hermes/cron/jobs.json'))
   j = next((j for j in d['jobs'] if j['id'] == '$JOB_ID'), None)
   if j:
       completed = j.get('repeat', {}).get('completed', 0)
       next_run = j.get('next_run_at')
       created = j.get('created_at')
       print(f'completed={completed} next_run_at={next_run} created_at={created}')
       # If completed counter is reliable, tick = completed + 1
   "

Caveat (verified 2026-07-12, cron 1f0822aae664 wa-cookies-poll): on the very first tick, repeat.completed = 0 AND last_run_at = null AND the JSON file may not have been flushed yet — jobs.json is updated by the gateway AFTER the prompt fires. Use the file mtime fallback below in that case.

2. File mtime fallback (works on tick #1, when jobs.json is stale):

   # wa-cookies.json was JUST written by THIS tick's browserclaw invocation
   stat -f '%Sm' /tmp/repro-<id>/wa-cookies.json
   # Compare against the original cron creation time:
   grep -A1 '"created_at"' ~/.hermes/cron/jobs.json | head -2 | grep -oE '20[0-9-]+T[0-9:.]+'
   # elapsed_minutes = (mtime - created_at) / 60 ; tick ≈ elapsed_minutes / schedule_minutes + 1
   

3. Compute from next_run_at + interval (works regardless of jobs.json freshness):

   python3 -c "
   import json, datetime
   j = json.load(open('$HOME/.hermes/cron/jobs.json'))
   target = next(j for j in j['jobs'] if '<your_job_name_substring>' in j['name'])
   created = datetime.datetime.fromisoformat(target['created_at'])
   interval = target['schedule']['minutes']
   # current tick = ceil((now - created) / interval)
   now = datetime.datetime.now(created.tzinfo)
   print(f'tick ≈ {((now - created).total_seconds() / 60 / interval + 1):.0f}')
   "
   

Absolute PATH note for hermes cron remove: under the env -i wrapper (per bashrc-profile-xapp-drift-blocks-launchd memory), which hermes returns $HOME/.local/bin/hermes. The cron prompt's self-cancel must use this absolute path or it will fail:

env -i HOME="$HOME" PATH="$HOME/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" \
  "$HOME/.local/bin/hermes" cron remove "$CRON_JOB_ID"

Verified worked example (2026-07-12, cron 1f0822aae664): tick #1 detected via file mtime of /tmp/repro-a1OGXH/wa-cookies.json (20:47:12) vs cron created_at (20:41:08), interval 5 min → tick = ⌈(20:47:12 − 20:41:08) / 5⌉ + 1 = 2 (conservative; the first tick ran ~20:46). jobs.json repeat.completed = 0 and last_run_at = null confirmed this was an early tick where the gateway hadn't yet flushed the run counter.

Hard constraints:

• ALWAYS env -i ... PATH=... for gh / browserclaw / git (per bashrc-profile-xapp-drift-blocks-launchd memory).
• NEVER open the draft PR without explicit user "go" in this thread.
• NEVER log full cookie values to Slack — use --summary only.
• If browserclaw errors with Keychain lookup → post the exact stderr.

**When to use this pattern:**
- The user has 0 cookies for the SPA domain but they are signed into Google/GitHub/etc. in Chrome
- The bug is per-campaign (not auth) and the fix path doesn't strictly require browser access
- You have other work to do while waiting (don't block the user)

**When NOT to use this pattern:**
- The cookies would never appear (e.g. wrong Chrome profile, no path forward to manual visit)
- The bug requires an interactive flow that cookies can't capture (drag-drop, OAuth callback, payment)

## Security implications (READ BEFORE USING)

Cookie decryption is **sensitive**. The keychain password unlocks every cookie Chrome has stored for the user — Slack `d` tokens, GitHub `user_session`, Google `SID`, banking sessions, etc. Operators MUST:

1. **Treat decrypted cookies like raw passwords.** Do not log full cookie values to Slack, GitHub PR comments, gist attachments, or any external surface. Prefer `--summary` when sharing evidence.
2. **Never commit the output JSON.** Add `cookies.json` and `*-cookies.json` to `.gitignore` immediately. Delete after use with `shred -u cookies.json` if the disk is encrypted, otherwise `rm` is sufficient on APFS.
3. **Run in a private context.** If you invoke this from an AO worker, treat the worker session as if it has root-level access to the user's identity. Do not dispatch this skill into shared / multi-tenant AO lanes.
4. **Respect the trust model.** This skill reads only the *current user's own* Chrome profile, using *that user's* macOS Keychain. It does not (and cannot) read another user's cookies without their Keychain password. Do not extend it to do so.
5. **No bypass claims.** This skill does not bypass 2FA, CAPTCHA, or anti-bot systems. It reuses an existing logged-in session. Do not advertise it as a "login bypass."
6. **Audit logging.** Every invocation should appear in the agent's session log. If you are dispatching this via AO, include `--summary` output in the worker report and never the raw cookie values.

## Trust model diagram

```text
┌──────────────┐    security find-generic-password   ┌──────────────────┐
│  user        │ ─────────────────────────────────▶ │  macOS Keychain   │
│  (you)       │ ◀─────── "Chrome Safe Storage" ─── │  Login keychain   │
└──────┬───────┘                                      └──────────────────┘
       │ grants access once per session
       ▼
┌──────────────┐    PBKDF2-HMAC-SHA1 (1003 iters)   ┌──────────────────┐
│ browserclaw  │ ─────────────────────────────────▶ │  AES-128-CBC key  │
│ cookies.py   │                                      └────────┬─────────┘
└──────┬───────┘                                               │
       │ reads Cookies SQLite (copy to tmp)                   │
       ▼                                                       ▼
┌──────────────┐   v10 || AES(plaintext)                  ┌──────────────┐
│   cookies    │ ──────decrypt──────────────────────────▶ │  JSON output │
│   .json      │                                          │  (Playwright) │
└──────────────┘                                          └──────────────┘

Test script

A bash regression test lives at tests/test_browserclaw_skill.sh (this repo). It verifies:

1. This SKILL.md exists and is non-empty.
2. browserclaw cookies decrypt is documented with a real example.
3. browserclaw cookies inject is documented with a real example.
4. The security warning section is present.
5. The installed browserclaw CLI exposes the cookies subcommand (real binary surface, not just docs).
6. An --help invocation of cookies decrypt returns exit code 0.

Run it from this repo:

bash tests/test_browserclaw_skill.sh

Eval criteria — "working" looks like

• browserclaw cookies decrypt --db <path> --output /tmp/c.json --domain-filter '%slack.com%' exits 0 and writes a JSON with >=1 cookie for an actively-used Slack profile.
• browserclaw cookies inject --cookies /tmp/c.json --goto https://app.slack.com/client --browser-channel chromium --headless --wait-after-load 5 --screenshot /tmp/proof.png exits 0, writes a non-zero PNG, and prints a non-empty --print-text if requested.
• End-to-end (decrypt → inject → screenshot) is captured as evidence for PR /es layer-2 verification on PR #6.

Cross-references

• Source repo: github.com/jleechanorg/browserclaw
• PR introducing the feature: #6 — feat(cookies): Chrome cookie decrypt + Playwright inject for reuse of logged-in sessions
• Module source: src/browserclaw/cookies.py (dataclasses, AES decrypt, Keychain lookup, JSON I/O)
• CLI source: src/browserclaw/cli.py (argparse for cookies decrypt / cookies inject)
• Tests (10 cases, all green on macOS): tests/test_cookies_decrypt.py
• Reference Chromium source: os_crypt_mac.mm (PBKDF2 params, AES key derivation)
• Inspiration: pycookiecheat (MIT) — adapted for Python 3.11+ and DB v24+ SHA256(host) prefix.
• Related Hermes skills: ~/.claude/skills/browser-testing (Playwright MCP for localhost UI testing, headless) — use this skill for session-less UI testing, not for "act as user X" flows.
• v2 design (validated 2026-07-30, NOT YET IMPLEMENTED): references/browserclaw-v2-design-2026-07-30.md — autonomous outcome-driven control plane, supersedes the "manual auth only" / "no auth bypass" ceiling. Captures the operator's three preference signals (no cookie promotion into BrowserClaw storage, env-configurable notifications defaulting to Hermes DM, automatic auth with manual fallback only after bounded recovery exhaustion). Read this before proposing any browserclaw feature work.

Version / metadata

• Last updated: 2026-07-18 (v0.3.0 — added v20/ABE bypass via headless Chrome + CDP Network.getAllCookies recipe; verified on TaxDome drive recovering 247 unique tax-domain cookies across Chrome Default + Aside Default)
• browserclaw version: 0.1.0 (cookies added in commit 9320bc0 on branch feat/cookie-decrypt-inject)
• Tracking PR: #6
• Hermes skill location: skills/browserclaw/SKILL.md (this file); also mirrored at ~/.claude/skills/browserclaw/SKILL.md

Multi-profile cookie scan — when the default Chrome profile returns 0 cookies

Before concluding "no session exists," sweep every local browser profile + non-Chrome browser. Sites like Venmo, niche SaaS tools, and personal banking may be logged in on Profile 1 / Profile 3 / Aside / Brave / Edge while Default has nothing. Full recipe, sweep loop, env -i wrapper, and the Gmail-as-data-fallback pattern in references/multi-profile-cookie-scan.md. TL;DR:

for prof in "Default" "Profile 1" "Profile 3"; do
  env -i HOME="$HOME" PATH="$HOME/.local/orch-venv/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" \
    browserclaw cookies decrypt --db "$HOME/Library/Application Support/Google/Chrome/$prof/Cookies" \
      --output "/tmp/${prof// /}-cookies.json" --domain-filter '%<target>%' --summary 2>&1 | head -3
done
# + Aside / Brave / Edge sweeps

If all return 0, run gog gmail search --account $[e-mail] "from:<domain> OR subject:<keyword>" to check whether the data is already emailed as monthly activity statements — many fintech / SaaS sites ship history emails. If Gmail also doesn't have it, the task needs a vendor-support / manual / alternate-source path; don't pretend headless injection will work.

When cookies decrypt returns empty values — v20 (App-Bound Encryption) bypass

When Chrome v120+ writes cookies with the v20 prefix, the Safe Storage + PBKDF2 key from the Keychain alone is insufficient — browserclaw cookies decrypt (verified 2026-07-18) returns cookies with length(value) populated but value="" for v20 entries, and silently skips the rest. The v20 prefix means App-Bound Encryption (ABE): the encrypted blob is wrapped with a key only the running Chrome process can decrypt.

Symptom: --summary shows non-zero lengths for hundreds of cookies, but cookies.json has value="" everywhere. --domain-filter '%<real-domain>%' returns N>0 cookies but no usable auth tokens.

Fix (verified 2026-07-18, TaxDome drive, 247 unique tax-domain cookies recovered): launch a headless Chrome with --remote-debugging-port=N pointing at a copy of the user's profile, then call CDP Network.getAllCookies — Chrome decrypts v20 in-process and returns plaintext. Full recipe in references/cdp-decrypt-via-headless-browser.md. TL;DR:

# 1. Copy profile (skip SingletonLock, SingletonSocket, SingletonCookie)
TMPDATA=/tmp/job-chrome-debug
mkdir -p "$TMPDATA/Default"
SRC="$HOME/Library/Application Support/Google/Chrome/Default"
for f in Cookies 'Local State' Preferences 'Secure Preferences' 'Web Data' 'Login Data'; do
  cp -L "$SRC/$f" "$TMPDATA/Default/$f" 2>/dev/null
done

# 2. Launch headless Chrome with CDP
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --headless=new --disable-gpu --no-sandbox \
  --remote-debugging-port=9222 \
  --user-data-dir="$TMPDATA" --profile-directory=Default \
  about:blank > /tmp/job-cdp.log 2>&1 &

# 3. CDP Network.getAllCookies via /tmp/job-cdp-cookies.mjs (Node + ws)
#    → outputs /tmp/job/cookies-decrypted.jsonl with v20 plaintext

Run multiple headless instances in parallel for Chrome + Aside + Brave + Edge — distinct ports (9222/9223/9224/...) and distinct --user-data-dir=. Verified 247 cookies across Chrome Default + Aside Default on 2026-07-18.

Then convert the JSONL output to Playwright storage_state and use cookies inject as normal, OR feed directly into curl --cookie-jar for backend API drives.

What this bypass does NOT solve: Cloudflare Turnstile on the first page load rejects headless Chrome UA. Once you have decrypted session cookies, drive via CDP Network.setCookie against the user's existing visible Chrome (or chrome --remote-debugging-port=9222 keeping their tabs) rather than a fresh headless instance.

Cookie freshness caveat: Cloudflare _abck / Akamai bm_sz rotate every 5-10 min. Drive portals within that window after dumping, or re-dump before each Cloudflare-fronted navigation.

Pair with

• references/gemini-share-link-stopping-pattern.md — the 2026-07-20 incident that prompted this rule; full failure-mode analysis + 3-layer closeout (skill + SOUL.md COMMIT + contract test in jleechanclaw PR #788). Read this whenever you're tempted to post an "unblock options" menu on auth-gate refusal.
• references/gemini-share-link-as-user.md — verified 5-step recipe (env-isolated browserclaw cookies decrypt → cookies inject with --browser-channel chromium --headless) for reading auth-gated share links as the user.
• references/multi-profile-cookie-scan.md — full multi-profile sweep loop + Gmail-as-data-fallback (2026-07-14)
• references/cdp-decrypt-via-headless-browser.md — v20 (App-Bound Encryption) bypass when cookies decrypt returns empty values; headless-Chrome + CDP Network.getAllCookies recipe (2026-07-18)
• references/multi-portal-cookie-replay.md — verified 10-portal pattern (filter → drive → mirror → cron-poll) from the 2026-07-18 tax-return drive; per-portal bot detection matrix + TaxDome end-to-end path
• references/gmail-as-fallback-when-sso-clickthrough-blocked.md — when same *.google.com cookies decrypt successfully but cookies inject against the vendor site (e.g. Monarch "Continue with Google") lands on the login form because SSO needs an interactive click-through headless can't drive. Verified 2026-07-22: Gmail via the same cookies works, vendor alert emails carry structured data (budget overruns, "Access Expired" notices, transaction amounts) for real analysis. Run the recipe first; do not propose an unblock menu.
• references/direct-graphql-stolen-cookie-auth.md — escape hatch when SSO-gated UI blocks Playwright: POST directly to the site's protected GraphQL/REST with stolen cookies + X-CSRFToken + correct Origin/Referer headers. Verified 2026-07-22 against https://api.monarch.com/graphql returning +$335,375.10 net worth (37 accounts) when Playwright headless couldn't drive Google SSO. Covers CSRF-header variants (Django/Laravel/ASP.NET/Express), error-code→cause matrix, and the P6 lesson that live API data can contradict earlier in-thread claims — always re-fetch and present the verified numbers plus a diff vs the prior claim.
• references/data-extraction-recipes-from-stolen-cookies.md — when auth is solved and you need the right operation names + query shapes to extract the actual data. Verified 2026-07-22 against Monarch: 4 GraphQL queries ( / / / ) that produced 389 daily snapshots, 13-month per-accountType decomposition, and monthly cashflow in one session. Covers the typed-filter-input shape ( instead of top-level vars), the requirement, the quirk (which gates which accounts appear in the dashboard trend), and how to detect single-day feed glitches ($552K plunge + $543K bounce in 24h = not real).