From d5d5bcd4909b08d3bae02b74b7ce2ff260676ffb Mon Sep 17 00:00:00 2001 From: Tianren Dong Date: Thu, 25 Jun 2026 21:06:39 -0400 Subject: Shorten README and move architecture docs --- docs/ARCHITECTURE.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/ARCHITECTURE.md (limited to 'docs') diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..4b2a561 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,74 @@ +# pi-chrome architecture + +`pi-chrome` connects Pi to your existing Chrome profile through a local-only bridge and an unpacked Chrome extension. + +```text + +----------------------+ +--------------------------+ + | Pi agent (terminal) | -- 127.0.0.1:17318 ->| Chrome extension | + | chrome_* tools | | (your real profile) | + +-----------+----------+ +-------------+------------+ + | same machine | + v v + Other Pi sessions Tabs you already have open + share same bridge (GitHub, Linear, Stripe, etc.) +``` + +## Components + +- **Pi extension** — exposes `chrome_*` tools and `/chrome` commands inside Pi. +- **Loopback bridge** — listens on `127.0.0.1:17318`; no external network bind by default. +- **Chrome companion extension** — loaded unpacked into your real Chrome profile. +- **Chrome debugger / CDP** — drives input, screenshots, network/console observation, and evaluation. + +## Session model + +Multiple Pi sessions can use same Chrome companion extension. First session opens local bridge; later sessions detect it and pipe commands through. + +Each Pi session owns its own automation target: + +- First chrome action without explicit target opens dedicated automation window. +- If separate window cannot be created, pi-chrome falls back to dedicated tab. +- Target survives `/reload` and Chrome service-worker restarts. +- Ownership is tracked by id and mirrored to `chrome.storage.session`. +- Cleanup closes only calling session's own target, never user tabs/windows or other sessions' targets. + +To point pi-chrome at an existing tab, pass `targetId`, `urlIncludes`, or `titleIncludes`. + +## Tab management guards + +`chrome_tab` management actions are guarded: + +- `activate`, `close`, `group`, and `ungroup` without explicit target act on session automation tab if it exists. +- If no automation tab exists, operation errors instead of touching your active tab. + +## Background mode + +By default, chrome calls run in background so Chrome does not steal focus. + +```text +/chrome background on # background mode +/chrome background off # foreground/watch mode +``` + +Per-call `background: false` brings Chrome forward for that action. Per-call `background: true` forces background. + +## Authorization + +Bridge connection alone is not enough. Chrome control stays locked until current Pi session runs: + +```text +/chrome authorize +``` + +Authorization expires after configured duration, on `/chrome revoke`, or when Pi exits. + +## Unpacked extension choice + +`pi-chrome` ships browser extension source as an unpacked folder on purpose: + +- easy to inspect before loading +- no Web Store release delay +- MIT-licensed source in repo +- `/chrome doctor` can compare loaded extension version against installed package + +Loaded extension has broad tab/scripting permissions inside profile where it is installed. Install only from trusted package source. -- cgit v1.2.3