pi-chrome 0.15.40 → 0.15.42
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,301 +1,145 @@
|
|
|
1
1
|
# pi-chrome
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Let [Pi](https://pi.dev) use your existing signed-in Chrome profile after explicit authorization.
|
|
4
4
|
|
|
5
|
-
**MIT · 0 runtime deps · loopback-only bridge (`127.0.0.1:17318`) ·
|
|
5
|
+
**MIT · 0 runtime deps · loopback-only bridge (`127.0.0.1:17318`) · inspectable unpacked Chrome extension.** Review [`extensions/chrome-profile-bridge/browser-extension/`](./extensions/chrome-profile-bridge/browser-extension) before loading. Verify setup with `/chrome doctor`.
|
|
6
6
|
|
|
7
7
|
```text
|
|
8
|
-
You: "Find my open GitHub PR tab, summarize review state, and screenshot
|
|
8
|
+
You: "Find my open GitHub PR tab, summarize review state, and screenshot failing CI."
|
|
9
9
|
Agent: chrome_tab(list) → chrome_snapshot(uid:…) → chrome_screenshot(...)
|
|
10
10
|
✓ 3 reviewers, 1 change requested, CI red on iOS. Saved → .pi/chrome-screenshots/ci.png
|
|
11
11
|
You: [keeps coding — agent never asked you to log in]
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
`pi-chrome`
|
|
14
|
+
`pi-chrome` runs through a small Chrome extension inside the Chrome profile **you already use** — including sites where you're already signed in. Agents can inspect or control Chrome only after you run `/chrome authorize` in current Pi session.
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
18
|
-
##
|
|
19
|
-
|
|
20
|
-
To install pi-chrome, run the following command:
|
|
18
|
+
## Install
|
|
21
19
|
|
|
22
20
|
```bash
|
|
23
21
|
pi install npm:pi-chrome
|
|
24
22
|
```
|
|
25
23
|
|
|
26
|
-
|
|
27
|
-
Then in Pi, run the next command, which will:
|
|
28
|
-
|
|
29
|
-
1. Reveal the bundled browser-extension folder in Finder, and copy the folder path to your clipboard.
|
|
30
|
-
2. Pop open the chrome://extensions webpage in Chrome.
|
|
31
|
-
|
|
32
|
-
In the Chrome Extensions page it opened, **YOU WILL NEED TO**:
|
|
33
|
-
|
|
34
|
-
1. Turn on **developer mode** (top right).
|
|
35
|
-
2. Click the **load unpacked** button (top left).
|
|
36
|
-
3. Use **Cmd + Shift + G** (Mac) or **Ctrl + L** (Windows/Linux) to open the folder path field.
|
|
37
|
-
4. **Cmd + V** (Mac) or **Ctrl + V** (Windows/Linux) to paste the copied path and press Enter.
|
|
38
|
-
5. You're done with the chrome extensions page, and you can continue with the rest of the installation commands
|
|
24
|
+
In Pi:
|
|
39
25
|
|
|
40
26
|
```text
|
|
41
27
|
/chrome onboard
|
|
42
28
|
```
|
|
43
29
|
|
|
44
|
-
|
|
30
|
+
This opens `chrome://extensions` and copies bundled extension path. In Chrome Extensions:
|
|
45
31
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
32
|
+
1. Turn on **Developer mode**.
|
|
33
|
+
2. Click **Load unpacked**.
|
|
34
|
+
3. Open path field with **Cmd+Shift+G** on macOS or **Ctrl+L** on Windows/Linux.
|
|
35
|
+
4. Paste copied path.
|
|
36
|
+
5. Press Enter.
|
|
50
37
|
|
|
51
|
-
|
|
38
|
+
Reload Pi so installed package loads:
|
|
52
39
|
|
|
53
40
|
```text
|
|
54
|
-
/
|
|
55
|
-
```
|
|
56
|
-
In the output, you just need to make sure the following line is present (It's okay if the other ones are still not checked):
|
|
57
|
-
|
|
58
|
-
✓ Chrome is connected (companion extension v0.15.36, responded in 11ms).
|
|
59
|
-
|
|
60
|
-
Lastly, authorize the current session by running:
|
|
61
|
-
```text
|
|
62
|
-
/chrome authorize
|
|
41
|
+
/reload
|
|
63
42
|
```
|
|
64
43
|
|
|
65
|
-
|
|
44
|
+
Check bridge:
|
|
66
45
|
|
|
67
46
|
```text
|
|
68
47
|
/chrome doctor
|
|
69
48
|
```
|
|
70
|
-
---
|
|
71
49
|
|
|
72
|
-
|
|
50
|
+
You should see:
|
|
73
51
|
|
|
74
52
|
```text
|
|
75
|
-
|
|
76
|
-
need my review today, sorted by staleness.
|
|
77
|
-
Don't click anything yet — just read and summarize.
|
|
53
|
+
✓ Chrome is connected (...)
|
|
78
54
|
```
|
|
79
55
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
---
|
|
83
|
-
|
|
84
|
-
## Killer recipes (copy-paste into Pi)
|
|
85
|
-
|
|
86
|
-
Each recipe assumes the relevant tab is already open in the Chrome you control.
|
|
87
|
-
|
|
88
|
-
**PR triage**
|
|
89
|
-
|
|
90
|
-
```text
|
|
91
|
-
You: "Look at my GitHub notifications tab and summarize the PRs needing my review today, sorted by staleness."
|
|
92
|
-
Agent: chrome_tab(list) → chrome_snapshot(uid:el-notifications) → chrome_evaluate(...)
|
|
93
|
-
✓ 7 PRs waiting on you. 2 stale >3d (storage-rewrite, billing-v2).
|
|
94
|
-
1 just turned CI-green (api-keys-prune). Full sorted list below.
|
|
95
|
-
You: [pastes the list straight into Linear]
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
**Linear standup**
|
|
99
|
-
|
|
100
|
-
```text
|
|
101
|
-
You: "Open my Linear current cycle and write a 5-bullet standup from it."
|
|
102
|
-
Agent: chrome_tab(activate, urlIncludes:"linear.app") → chrome_snapshot(uid:el-cycle) → chrome_evaluate(...)
|
|
103
|
-
✓ 5 in-progress, 2 blocked. Standup draft:
|
|
104
|
-
• Shipped: bridge auto-recover. • In flight: input reliability path.
|
|
105
|
-
• Blocked: vendor portal CSP (waiting on infra).
|
|
106
|
-
• Next: benchmark v2. • Risk: none today.
|
|
107
|
-
You: [drops it into #standup]
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
**Bug repro with evidence**
|
|
111
|
-
|
|
112
|
-
```text
|
|
113
|
-
You: "Reproduce the checkout 500 on staging. Save a screenshot at each step under ./repro/."
|
|
114
|
-
Agent: chrome_navigate(staging) → chrome_click(uid:el-add-to-cart) → chrome_screenshot(./repro/01-cart.png)
|
|
115
|
-
→ chrome_click(uid:el-checkout) → chrome_list_network_requests() → chrome_screenshot(./repro/02-500.png)
|
|
116
|
-
✓ POST /api/checkout → 500. Response body saved → ./repro/checkout-500.json
|
|
117
|
-
3 screenshots in ./repro/. Trigger: missing tax_id when cart contains digital goods.
|
|
118
|
-
You: [files the ticket with the folder attached]
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
<details>
|
|
122
|
-
<summary><strong>More recipes</strong> (form auto-fill, admin cross-check, visual diff, auth-only data pull, network forensics, file upload)</summary>
|
|
123
|
-
|
|
124
|
-
**Form auto-fill (no submit)**
|
|
125
|
-
> Open the vendor portal, fill the new-vendor form from this JSON, stop before submit.
|
|
126
|
-
|
|
127
|
-
**Admin cross-check**
|
|
128
|
-
> Across my Stripe / Postmark / our admin tabs, find any user where state disagrees.
|
|
129
|
-
|
|
130
|
-
**Local dev visual diff**
|
|
131
|
-
> Snapshot `localhost:3000` and the staging URL of the same page; tell me what's visually different.
|
|
132
|
-
|
|
133
|
-
**Auth-only data pull**
|
|
134
|
-
> Open my analytics dashboard tab and pull today's KPIs from the page.
|
|
135
|
-
|
|
136
|
-
**Network forensics**
|
|
137
|
-
> Reproduce the checkout bug, find the failing API call, and dump its response body.
|
|
138
|
-
|
|
139
|
-
**File upload through React**
|
|
140
|
-
> Open the photo uploader, upload `./fixtures/sample.png`, confirm the preview renders.
|
|
141
|
-
|
|
142
|
-
</details>
|
|
143
|
-
|
|
144
|
-
---
|
|
145
|
-
|
|
146
|
-
## Verifiable actions
|
|
147
|
-
|
|
148
|
-
Input tools return structured details such as the coordinates used, target tag, uploaded paths, key pressed, or scroll distance. For click/type/fill/key calls, pass `includeSnapshot: true` to get a fresh page snapshot in the same result:
|
|
56
|
+
Authorize current session:
|
|
149
57
|
|
|
150
58
|
```text
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
snapshot: { title, url, text, elements:[...] }
|
|
59
|
+
/chrome authorize
|
|
60
|
+
/chrome doctor
|
|
154
61
|
```
|
|
155
62
|
|
|
156
|
-
|
|
63
|
+
Second doctor run should show all checks passing.
|
|
157
64
|
|
|
158
65
|
---
|
|
159
66
|
|
|
160
|
-
## What
|
|
161
|
-
|
|
162
|
-
**21 tools**, grouped by job. Every one runs against your already-open tabs.
|
|
163
|
-
|
|
164
|
-
| Category | Tools |
|
|
165
|
-
| --------------- | ---------------------------------------------------------------------------------------------- |
|
|
166
|
-
| **Tabs** | `chrome_tab` (list/new/activate/close/version), `chrome_launch` |
|
|
167
|
-
| **Inspect** | `chrome_snapshot` (concise observation: layout, actions, forms, page map, query matches, diff + stable uids), `chrome_find` (query → ranked uids), `chrome_inspect` (deep single-element context), `chrome_screenshot`, `chrome_evaluate` |
|
|
168
|
-
| **Navigate** | `chrome_navigate` (with optional `initScript` at `document_start`), `chrome_wait_for` |
|
|
169
|
-
| **Interact** | `chrome_click`, `chrome_type`, `chrome_fill`, `chrome_key`, `chrome_hover` |
|
|
170
|
-
| **Gesture** | `chrome_drag` (Chrome pointer drag), `chrome_scroll` (wheel + momentum), `chrome_tap` (touch) |
|
|
171
|
-
| **Files** | `chrome_upload_file` (Chrome file-input control; no native picker) |
|
|
172
|
-
| **Observe** | `chrome_list_console_messages`, `chrome_list_network_requests`, `chrome_get_network_request` (with response body) |
|
|
67
|
+
## What it can do
|
|
173
68
|
|
|
174
|
-
|
|
69
|
+
Pi gets browser tools for:
|
|
175
70
|
|
|
176
|
-
|
|
71
|
+
- **Tabs** — list, open, activate, close, launch Chrome.
|
|
72
|
+
- **Inspect** — page snapshots, element search/inspection, screenshots, JS evaluation.
|
|
73
|
+
- **Navigate/wait** — open URLs, wait for page state.
|
|
74
|
+
- **Interact** — click, type, fill, key, hover, drag, scroll, tap.
|
|
75
|
+
- **Files** — upload files through `<input type=file>` without native picker.
|
|
76
|
+
- **Observe** — console logs, network requests, response bodies.
|
|
177
77
|
|
|
178
|
-
|
|
78
|
+
Input tools return structured verification data. Pass `includeSnapshot: true` on click/type/fill/key calls to get fresh page state in same result.
|
|
179
79
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
- **Per session.** Each Pi session owns its *own* automation window, so concurrent sessions (which all share one companion extension) never fight over a tab.
|
|
183
|
-
- **Survives `/reload` and Chrome service-worker restarts.** Ownership is tracked by id and mirrored to `chrome.storage.session`, so the window is reused rather than orphaned.
|
|
184
|
-
- **Cleanup is safe.** The dedicated target is closed when you revoke Chrome control (`/chrome revoke`) and on real session end — never on `/reload`. Cleanup only ever closes the calling session's own automation window/tab; user tabs/windows and other sessions' targets are never closed. Cleanup is fire-and-forget so it never blocks `/quit`, `/reload`, or session end.
|
|
185
|
-
- **Management actions are guarded.** `chrome_tab` `activate`/`close`/`group`/`ungroup` with no explicit target act on the session's automation tab if it exists, otherwise they error instead of touching your active tab.
|
|
186
|
-
|
|
187
|
-
### Known limits vs. human Chrome use
|
|
188
|
-
|
|
189
|
-
pi-chrome is strongest on web-page workflows exposed through DOM, screenshots, tabs, and Chrome input. It is not a full human/OS substitute. Current limitations include native Chrome/OS surfaces (print/save dialogs, permission bubbles, password-manager prompts), cross-origin iframe DOM access, rich multitouch/pinch/stylus gestures, visual CAPTCHA/bot challenges, hardware-backed auth (passkeys/security keys/biometrics), and arbitrary OS app interaction. For strict-CSP pages, use screenshot + coordinate input when `chrome_snapshot`/`chrome_evaluate` are blocked.
|
|
80
|
+
Tool parameters and gotchas are documented inline in Pi.
|
|
190
81
|
|
|
191
82
|
---
|
|
192
83
|
|
|
193
|
-
##
|
|
194
|
-
|
|
195
|
-
`pi-chrome` drives interactive controls through Chrome's real input layer: clicks, typing, fill, keys, hover, drag, scroll, and touch. Under the hood it uses `chrome.debugger` / CDP, so input satisfies normal user-activation gates. Chrome may show the *"Pi Chrome Connector started debugging this browser"* banner while attached.
|
|
196
|
-
|
|
197
|
-
### Authorization
|
|
84
|
+
## Safety model
|
|
198
85
|
|
|
199
|
-
Chrome control is locked by default.
|
|
86
|
+
Chrome control is locked by default. Authorize per Pi session:
|
|
200
87
|
|
|
201
88
|
```text
|
|
202
|
-
/chrome authorize #
|
|
203
|
-
/chrome authorize 30m #
|
|
204
|
-
/chrome authorize
|
|
205
|
-
/chrome authorize indefinite # authorize until revoked or Pi exits
|
|
89
|
+
/chrome authorize # 15 minutes
|
|
90
|
+
/chrome authorize 30m # custom duration
|
|
91
|
+
/chrome authorize indefinite
|
|
206
92
|
/chrome revoke # lock again
|
|
207
|
-
/chrome status
|
|
93
|
+
/chrome status
|
|
208
94
|
```
|
|
209
95
|
|
|
210
|
-
|
|
96
|
+
Safety properties:
|
|
211
97
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
/chrome background # toggle for the whole session
|
|
218
|
-
/chrome background on # run in background (default)
|
|
219
|
-
/chrome background off # bring Chrome forward so you can watch
|
|
220
|
-
```
|
|
98
|
+
- Extension runs in your real Chrome profile and has broad tab/scripting permissions. Install only from trusted package source.
|
|
99
|
+
- Pi side binds to `127.0.0.1:17318` only; no default network exposure.
|
|
100
|
+
- Bridge rejects browser-origin command requests, so ordinary web pages cannot drive it through CORS.
|
|
101
|
+
- Each Pi session gets its own automation target; user tabs/windows are not closed by cleanup.
|
|
102
|
+
- `/chrome revoke` closes only calling session's automation target.
|
|
221
103
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
### Diagnostics
|
|
225
|
-
|
|
226
|
-
- `/chrome doctor` — single command: connectivity, extension version, bridge owner, version drift, MAIN-world helper injection, `chrome_evaluate("1+1") === 2`, fingerprint flags.
|
|
227
|
-
- `/chrome onboard` — guided first-time setup.
|
|
228
|
-
- `/chrome status` — current connection, authorization, and background state.
|
|
229
|
-
- `/chrome background status` — current watch/background setting.
|
|
230
|
-
|
|
231
|
-
If the loaded Chrome extension is older than `pi-chrome` on disk, `/chrome doctor` tells you to reload it from `chrome://extensions`.
|
|
104
|
+
Security details: [`SECURITY.md`](./SECURITY.md). Architecture details: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
|
|
232
105
|
|
|
233
106
|
---
|
|
234
107
|
|
|
235
|
-
##
|
|
108
|
+
## Commands
|
|
236
109
|
|
|
237
110
|
```text
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
automatically Linear, Stripe, etc.)
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
Multiple Pi sessions (planner / worker / audit) can all drive the same Chrome at once. The first session opens the local bridge; later sessions detect it and pipe their commands through.
|
|
250
|
-
|
|
251
|
-
---
|
|
252
|
-
|
|
253
|
-
## Built-in benchmark suite
|
|
254
|
-
|
|
255
|
-
[`test-suite/`](./test-suite) is a benchmark for **any** browser-control agent (not just pi-chrome). It includes **42 primitive challenges** plus **4 hermetic BrowserGym-style long-horizon tasks**.
|
|
256
|
-
|
|
257
|
-
Scoring tracks expected outcomes per challenge rather than raw PASS count, so tools are judged against their declared browser-control capability. Unit challenges are split into gate buckets:
|
|
258
|
-
|
|
259
|
-
- `core` — expected release blockers for normal trusted-mode browser control.
|
|
260
|
-
- `conditional` — capability/environment gated (clipboard, touch, dialogs, native UI, etc.).
|
|
261
|
-
- `quality` — adversarial humanization/fingerprint signals; report trends, don't block general release by default.
|
|
262
|
-
|
|
263
|
-
Each challenge exposes `window.__verdict` / `window.__reason` / `window.__events` and a manifest entry with expected results per mode.
|
|
264
|
-
|
|
265
|
-
```bash
|
|
266
|
-
cd test-suite && python3 -m http.server 8765
|
|
267
|
-
# open http://127.0.0.1:8765/ in the Chrome window pi-chrome controls
|
|
111
|
+
/chrome onboard # guided setup
|
|
112
|
+
/chrome doctor # connectivity + version + eval checks
|
|
113
|
+
/chrome status # connection + auth + background state
|
|
114
|
+
/chrome authorize [duration]
|
|
115
|
+
/chrome revoke
|
|
116
|
+
/chrome background on # default: don't steal focus
|
|
117
|
+
/chrome background off # foreground/watch mode
|
|
118
|
+
/chrome background status
|
|
268
119
|
```
|
|
269
120
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
If you build a competing tool, please open a PR with your scores. We benchmark in public.
|
|
121
|
+
If loaded extension is older than installed `pi-chrome`, `/chrome doctor` tells you to reload it from `chrome://extensions`.
|
|
273
122
|
|
|
274
123
|
---
|
|
275
124
|
|
|
276
|
-
##
|
|
277
|
-
|
|
278
|
-
**Unpacked on purpose.** pi-chrome ships as an inspectable, MIT-licensed extension folder you load once with Developer Mode, so the local bridge and browser permissions are easy to audit and update without a Web Store release cycle. Every line is yours to read in [`extensions/chrome-profile-bridge/browser-extension/`](./extensions/chrome-profile-bridge/browser-extension). `/chrome doctor` reports the loaded extension version and warns when it drifts from your installed `pi-chrome`.
|
|
125
|
+
## Limits
|
|
279
126
|
|
|
280
|
-
|
|
127
|
+
`pi-chrome` works best on web-page workflows exposed through DOM, screenshots, tabs, network, console, and Chrome input. It is not full OS automation.
|
|
281
128
|
|
|
282
|
-
|
|
129
|
+
Current limits include native Chrome/OS surfaces, print/save dialogs, permission bubbles, password-manager prompts, cross-origin iframe DOM access, CAPTCHA/bot challenges, passkeys/security keys/biometrics, rich multitouch/pinch/stylus gestures, and arbitrary desktop apps.
|
|
283
130
|
|
|
284
|
-
|
|
131
|
+
For strict-CSP pages, use screenshots + coordinate input when snapshot/evaluate paths are blocked.
|
|
285
132
|
|
|
286
133
|
---
|
|
287
134
|
|
|
288
|
-
##
|
|
289
|
-
|
|
290
|
-
`pi-chrome` is actively shipped. Things on the near roadmap:
|
|
291
|
-
|
|
292
|
-
- More observability tools (DOM mutation streams, performance traces)
|
|
293
|
-
- First-class cross-origin iframe + Shadow-DOM uid stability across snapshots
|
|
294
|
-
- Native-browser surface coverage where extension APIs allow it (downloads, permissions, context menus)
|
|
295
|
-
- Web Push & service worker introspection
|
|
296
|
-
- Recorder mode that emits agent prompts from your own clicks
|
|
135
|
+
## Docs
|
|
297
136
|
|
|
298
|
-
|
|
137
|
+
- Examples: [`docs/EXAMPLES.md`](./docs/EXAMPLES.md)
|
|
138
|
+
- FAQ: [`docs/FAQ.md`](./docs/FAQ.md)
|
|
139
|
+
- Comparison: [`docs/COMPARISON.md`](./docs/COMPARISON.md)
|
|
140
|
+
- Security: [`SECURITY.md`](./SECURITY.md)
|
|
141
|
+
- Benchmark suite: [`test-suite/README.md`](./test-suite/README.md)
|
|
142
|
+
- Architecture: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
|
|
299
143
|
|
|
300
144
|
---
|
|
301
145
|
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# pi-chrome architecture
|
|
2
|
+
|
|
3
|
+
`pi-chrome` connects Pi to your existing Chrome profile through a local-only bridge and an unpacked Chrome extension.
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
+----------------------+ +--------------------------+
|
|
7
|
+
| Pi agent (terminal) | -- 127.0.0.1:17318 ->| Chrome extension |
|
|
8
|
+
| chrome_* tools | | (your real profile) |
|
|
9
|
+
+-----------+----------+ +-------------+------------+
|
|
10
|
+
| same machine |
|
|
11
|
+
v v
|
|
12
|
+
Other Pi sessions Tabs you already have open
|
|
13
|
+
share same bridge (GitHub, Linear, Stripe, etc.)
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Components
|
|
17
|
+
|
|
18
|
+
- **Pi extension** — exposes `chrome_*` tools and `/chrome` commands inside Pi.
|
|
19
|
+
- **Loopback bridge** — listens on `127.0.0.1:17318`; no external network bind by default.
|
|
20
|
+
- **Chrome companion extension** — loaded unpacked into your real Chrome profile.
|
|
21
|
+
- **Chrome debugger / CDP** — drives input, screenshots, network/console observation, and evaluation.
|
|
22
|
+
|
|
23
|
+
## Session model
|
|
24
|
+
|
|
25
|
+
Multiple Pi sessions can use same Chrome companion extension. First session opens local bridge; later sessions detect it and pipe commands through.
|
|
26
|
+
|
|
27
|
+
Each Pi session owns its own automation target:
|
|
28
|
+
|
|
29
|
+
- First chrome action without explicit target opens dedicated automation window.
|
|
30
|
+
- If separate window cannot be created, pi-chrome falls back to dedicated tab.
|
|
31
|
+
- Target survives `/reload` and Chrome service-worker restarts.
|
|
32
|
+
- Ownership is tracked by id and mirrored to `chrome.storage.session`.
|
|
33
|
+
- Cleanup closes only calling session's own target, never user tabs/windows or other sessions' targets.
|
|
34
|
+
|
|
35
|
+
To point pi-chrome at an existing tab, pass `targetId`, `urlIncludes`, or `titleIncludes`.
|
|
36
|
+
|
|
37
|
+
## Tab management guards
|
|
38
|
+
|
|
39
|
+
`chrome_tab` management actions are guarded:
|
|
40
|
+
|
|
41
|
+
- `activate`, `close`, `group`, and `ungroup` without explicit target act on session automation tab if it exists.
|
|
42
|
+
- If no automation tab exists, operation errors instead of touching your active tab.
|
|
43
|
+
|
|
44
|
+
## Background mode
|
|
45
|
+
|
|
46
|
+
By default, chrome calls run in background so Chrome does not steal focus.
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
/chrome background on # background mode
|
|
50
|
+
/chrome background off # foreground/watch mode
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Per-call `background: false` brings Chrome forward for that action. Per-call `background: true` forces background.
|
|
54
|
+
|
|
55
|
+
## Authorization
|
|
56
|
+
|
|
57
|
+
Bridge connection alone is not enough. Chrome control stays locked until current Pi session runs:
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
/chrome authorize
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Authorization expires after configured duration, on `/chrome revoke`, or when Pi exits.
|
|
64
|
+
|
|
65
|
+
## Unpacked extension choice
|
|
66
|
+
|
|
67
|
+
`pi-chrome` ships browser extension source as an unpacked folder on purpose:
|
|
68
|
+
|
|
69
|
+
- easy to inspect before loading
|
|
70
|
+
- no Web Store release delay
|
|
71
|
+
- MIT-licensed source in repo
|
|
72
|
+
- `/chrome doctor` can compare loaded extension version against installed package
|
|
73
|
+
|
|
74
|
+
Loaded extension has broad tab/scripting permissions inside profile where it is installed. Install only from trusted package source.
|
package/package.json
CHANGED