playwright-my-chrome AGENTS.md

AGENTS.md

This file provides guidance to coding agents working with code in this repository. It is the single source of truth; CLAUDE.md is a symlink to it.

What this repository is

One published Agent Skill, skills/playwright-my-chrome/, that lets an agent drive the Chrome the user already has open and signed in. Everything shipped to users lives in that directory; the repository root only holds docs, tests, and CI. macOS and Google Chrome only.

Commit and push

Never commit or push to the main branch. Work on a branch and open a pull request.

Commands

npm run lint      # shellcheck + bash -n on every .sh, then tests/validate_skill.py
npm test          # tests/run.sh, the 21 behavior tests (about 12s)
npm run verify    # both
npx [email protected] install . --list   # third release check, Skills CLI discovery

npm run lint needs shellcheck on PATH (brew install shellcheck).

tests/run.sh has no filter flag. It is fast enough to run whole; to isolate one case, comment out the other calls in the invocation list at the bottom of the file.

Before any manual check against real Chrome, reinstall first. npx skills install copies the skill directory instead of linking it, so an installed copy goes stale as soon as scripts/ changes and would silently test old code:

npx skills install . --skill playwright-my-chrome --global \
  --agent codex --agent claude-code

Then run the wrapper from the installed path, not from this repository.

Architecture

scripts/playwright-my-chrome.sh (about 1800 lines of bash) is the product. It is a fail-closed wrapper around an already-installed @playwright/cli, not a library. Reading it top to bottom gives the whole design:

1. Preamble resolves the CLI and Node from fixed absolute locations (nvm, Volta, Homebrew, /usr/local), never through caller PATH, then resets PATH to system directories so nothing secret-bearing can be shimmed.
2. Runtime directory under the user's Caches folder must be private, mode 0700, non-symlink, and carry a claim file. The wrapper cds there for every CLI call, which is how one shared session named mychrome stays the same from any repository: Playwright CLI picks its daemon session from the nearest .playwright folder.
3. Attachment (attach_session) is the security core. It requires exactly one normal Chrome main process already running, reads the Keychain token only at that point, writes it to the child as an environment variable, and compares the full Chrome PID set immediately before and after. A changed PID set, or a Chrome command line still carrying the token, detaches and demands token rotation.
4. Cleanup paths (scrub_known_output, finalize_sanitation, remove_known_output) delete only what private, mode-0600, non-symlink metadata files name, and refuse traversal-shaped paths.
5. Dispatch at the bottom is an allowlist. open, raw attach, show, install, close-all, and kill-all are rejected locally. Unknown commands go through ensure_session and are forwarded with the session flag and token redaction.