my-pi/pi-chrome/CONTRIBUTING.md

Contributing to pi-chrome

Thanks for considering a contribution. pi-chrome aims to be the de-facto browser-control toolkit for Pi agents — that means a few non-negotiables.

Non-negotiables

1. No re-login. Every change must keep working against the user's already-signed-in Chrome profile. Anything that requires a fresh profile or extra auth steps is out of scope.
2. Verifiable action results. Input tools must return structured details and support includeSnapshot where verification matters. Agents need enough evidence to avoid blind retries.
3. Chrome real input. Interactive controls use Chrome's input layer through chrome.debugger; do not re-expose synthetic/untrusted input as public UX.
4. Benchmarks gate features. Add a page in test-suite/ that fails before your change and passes after. We accept PRs faster when there's a green/red verdict to point at.

Local dev

# Link from a checkout
pi install ./pi-chrome

# Run the benchmark dashboard
cd test-suite
python3 -m http.server 8765
# open http://127.0.0.1:8765/ in the Chrome window pi-chrome controls

Adding a new tool

1. Register in extensions/chrome-profile-bridge/index.ts (the register*Tool calls near line 840+).
2. Implement the handler in extensions/chrome-profile-bridge/browser-extension/service_worker.js.
3. Return structured details and support includeSnapshot for user-visible state changes when relevant.
4. Add a benchmark page under test-suite/challenges/ and a manifest entry.
5. Update README.md "What an agent gets" table.
6. Add a CHANGELOG.md entry.

Filing a bug

Include:

• /chrome doctor output
• pi-chrome version + extension version (the doctor output prints both)
• The exact tool call + the result envelope you got
• Page URL or a minimal repro page in test-suite/

Releasing

• Bump package.json version.
• Move CHANGELOG.md notes from the working section to the new version header.
• npm publish --access public.

Code of conduct

Be kind, be precise, ship things. PRs that break the "no re-login" promise will be closed with a note explaining which non-negotiable they hit.