pi-chrome architecture

pi-chrome connects Pi to your existing Chrome profile through a local-only bridge and an unpacked Chrome extension.

  +----------------------+                       +--------------------------+
  |  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.

/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:

/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.

3.0 KiB Raw Blame History