1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
# pi-chrome
> Let [Pi](https://pi.dev) use your existing signed-in Chrome profile after explicit authorization.
**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`.
```text
You: "Find my open GitHub PR tab, summarize review state, and screenshot failing CI."
Agent: chrome_tab(list) → chrome_snapshot(uid:…) → chrome_screenshot(...)
✓ 3 reviewers, 1 change requested, CI red on iOS. Saved → .pi/chrome-screenshots/ci.png
You: [keeps coding — agent never asked you to log in]
```
`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.
---
## Install
```bash
pi install npm:pi-chrome
```
In Pi:
```text
/chrome onboard
```
This opens `chrome://extensions` and copies bundled extension path. In Chrome Extensions:
1. Turn on **Developer mode**.
2. Click **Load unpacked**.
3. Open path field with **Cmd+Shift+G** on macOS or **Ctrl+L** on Windows/Linux.
4. Paste copied path.
5. Press Enter.
Reload Pi so installed package loads:
```text
/reload
```
Check bridge:
```text
/chrome doctor
```
You should see:
```text
✓ Chrome is connected (...)
```
Authorize current session:
```text
/chrome authorize
/chrome doctor
```
Second doctor run should show all checks passing.
---
## What it can do
Pi gets browser tools for:
- **Tabs** — list, open, activate, close, launch Chrome.
- **Inspect** — page snapshots, element search/inspection, screenshots, JS evaluation.
- **Navigate/wait** — open URLs, wait for page state.
- **Interact** — click, type, fill, key, hover, drag, scroll, tap.
- **Files** — upload files through `<input type=file>` without native picker.
- **Observe** — console logs, network requests, response bodies.
Input tools return structured verification data. Pass `includeSnapshot: true` on click/type/fill/key calls to get fresh page state in same result.
Tool parameters and gotchas are documented inline in Pi.
---
## Safety model
Chrome control is locked by default. Authorize per Pi session:
```text
/chrome authorize # 15 minutes
/chrome authorize 30m # custom duration
/chrome authorize indefinite
/chrome revoke # lock again
/chrome status
```
Safety properties:
- Extension runs in your real Chrome profile and has broad tab/scripting permissions. Install only from trusted package source.
- Pi side binds to `127.0.0.1:17318` only; no default network exposure.
- Bridge rejects browser-origin command requests, so ordinary web pages cannot drive it through CORS.
- Each Pi session gets its own automation target; user tabs/windows are not closed by cleanup.
- `/chrome revoke` closes only calling session's automation target.
Security details: [`SECURITY.md`](./SECURITY.md). Architecture details: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
---
## Commands
```text
/chrome onboard # guided setup
/chrome doctor # connectivity + version + eval checks
/chrome status # connection + auth + background state
/chrome authorize [duration]
/chrome revoke
/chrome background on # default: don't steal focus
/chrome background off # foreground/watch mode
/chrome background status
```
If loaded extension is older than installed `pi-chrome`, `/chrome doctor` tells you to reload it from `chrome://extensions`.
---
## Limits
`pi-chrome` works best on web-page workflows exposed through DOM, screenshots, tabs, network, console, and Chrome input. It is not full OS automation.
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.
For strict-CSP pages, use screenshots + coordinate input when snapshot/evaluate paths are blocked.
---
## Docs
- Examples: [`docs/EXAMPLES.md`](./docs/EXAMPLES.md)
- FAQ: [`docs/FAQ.md`](./docs/FAQ.md)
- Comparison: [`docs/COMPARISON.md`](./docs/COMPARISON.md)
- Security: [`SECURITY.md`](./SECURITY.md)
- Benchmark suite: [`test-suite/README.md`](./test-suite/README.md)
- Architecture: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
---
## License
MIT. See [LICENSE](./LICENSE).
|
