gazesight 0.5.0 → 0.5.2
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 +128 -57
- package/dist/chrome/background.js +1 -1
- package/dist/chrome/manifest.json +2 -2
- package/dist/chrome/popup.html +2 -2
- package/dist/chrome/popup.js +1 -1
- package/dist/cli/index.js +393 -177
- package/dist/firefox/background.js +21 -21
- package/dist/firefox/manifest.json +90 -90
- package/dist/firefox/popup.html +2 -2
- package/dist/firefox/popup.js +1 -1
- package/dist/gazesight-firefox.xpi +0 -0
- package/dist/mcp/index.js +2418 -1397
- package/package.json +15 -4
package/README.md
CHANGED
|
@@ -1,112 +1,183 @@
|
|
|
1
1
|
# GazeSight
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Browser vision for coding agents.**
|
|
4
4
|
|
|
5
5
|
**Let your coding agent see what you see.**
|
|
6
6
|
|
|
7
|
-
GazeSight
|
|
7
|
+
GazeSight connects Claude Code and OpenAI Codex to the browser you already use. Through MCP, agents can capture the page, inspect the DOM, interact with elements, read diagnostics, and verify visual changes against a reference.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
- Website: [gazesight.dev](https://www.gazesight.dev/)
|
|
10
|
+
- npm: [gazesight](https://www.npmjs.com/package/gazesight)
|
|
11
|
+
- Browsers: Firefox and Chrome
|
|
12
|
+
- Public MCP tools: exactly 25
|
|
13
|
+
- Architecture: local-first, with no GazeSight cloud capture backend
|
|
14
|
+
|
|
15
|
+
## Choose your setup
|
|
16
|
+
|
|
17
|
+
### GazeSight Desktop — recommended direction
|
|
18
|
+
|
|
19
|
+
GazeSight Desktop provides the simplest onboarding model: it embeds its own runtime, so GazeSight itself does not require a system Node.js installation. It detects Claude Code and Codex, configures lightweight MCP adapters, and owns one shared browser bridge.
|
|
20
|
+
|
|
21
|
+
Desktop `0.6.0-beta.1` is currently in release-candidate preparation and is **not yet publicly downloadable**. No public Desktop download link is provided until signed artifacts and the required platform validation are complete.
|
|
22
|
+
|
|
23
|
+
### npm / CLI — advanced, available now
|
|
24
|
+
|
|
25
|
+
The npm package is the currently available installation path. It requires Node.js 20 or newer.
|
|
26
|
+
|
|
27
|
+
Run without a global installation:
|
|
10
28
|
|
|
11
29
|
```sh
|
|
12
30
|
npx gazesight setup
|
|
13
31
|
```
|
|
14
32
|
|
|
15
|
-
|
|
33
|
+
Or install the CLI globally:
|
|
16
34
|
|
|
17
|
-
|
|
35
|
+
```sh
|
|
36
|
+
npm install -g gazesight
|
|
37
|
+
gazesight setup
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Configure a specific coding agent when needed:
|
|
18
41
|
|
|
19
42
|
```sh
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
43
|
+
gazesight setup --client claude
|
|
44
|
+
gazesight setup --client codex
|
|
45
|
+
gazesight setup --client both
|
|
23
46
|
```
|
|
24
47
|
|
|
48
|
+
Useful commands:
|
|
49
|
+
|
|
25
50
|
```sh
|
|
26
|
-
|
|
51
|
+
gazesight --help
|
|
52
|
+
gazesight doctor
|
|
53
|
+
gazesight pair
|
|
27
54
|
```
|
|
28
55
|
|
|
29
|
-
|
|
30
|
-
2. Install a compatible extension: **Firefox 0.4.0+** from Mozilla Add-ons or **Chrome 0.2.0+** by loading the packaged extension manually while Chrome Web Store publication remains pending.
|
|
31
|
-
3. Open GazeSight and click **Connect to GazeSight**. Confirm that the six-digit verification code matches the terminal, then explicitly approve it there. The code expires and is not the permanent credential.
|
|
32
|
-
4. Open your local project in your browser, keep its tab active, and click **Use this tab**. Pairing never selects or authorizes a tab automatically.
|
|
33
|
-
5. Restart your coding agent to load MCP, then run `gazesight doctor` while its GazeSight connection is active.
|
|
34
|
-
6. Ask your agent: "Use GazeSight visual_capture to inspect my active preview tab." The image arrives directly as MCP image content.
|
|
56
|
+
`setup` uses the official agent CLI when it is available and does not overwrite unrelated MCP server entries. `doctor` is read-only. `pair` can connect another browser or revoke an existing browser pairing.
|
|
35
57
|
|
|
36
|
-
|
|
58
|
+
## Install a browser extension
|
|
37
59
|
|
|
38
|
-
|
|
60
|
+
Use an official public listing:
|
|
39
61
|
|
|
40
|
-
|
|
62
|
+
- [Firefox — Mozilla Add-ons](https://addons.mozilla.org/firefox/addon/6a2319d4fa544731884d/) (`0.5.0`)
|
|
63
|
+
- [Chrome — Chrome Web Store](https://chromewebstore.google.com/detail/gazesight/hikhblabkhbaoilcffenldphdkjdmphc) (`0.3.0`)
|
|
41
64
|
|
|
42
|
-
|
|
65
|
+
Developer builds and unpacked extensions are separate development workflows. They are not required for normal installation.
|
|
43
66
|
|
|
44
|
-
|
|
67
|
+
## First run
|
|
45
68
|
|
|
46
|
-
|
|
69
|
+
1. Install or configure GazeSight.
|
|
70
|
+
2. Install the Firefox or Chrome extension from its official listing.
|
|
71
|
+
3. Open the extension and choose **Connect to GazeSight**.
|
|
72
|
+
4. Open the page you want to share.
|
|
73
|
+
5. Click **Use this tab** in that tab.
|
|
74
|
+
6. Use GazeSight from Claude Code or Codex.
|
|
47
75
|
|
|
48
|
-
|
|
76
|
+
Pairing a browser does **not** authorize a tab. The active target changes only after an explicit **Use this tab** action. Reloads or navigations that invalidate the authorization require another explicit selection.
|
|
49
77
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
78
|
+
## Desktop architecture
|
|
79
|
+
|
|
80
|
+
```text
|
|
81
|
+
Claude Code / Codex
|
|
82
|
+
↓
|
|
83
|
+
MCP stdio adapters
|
|
84
|
+
↓
|
|
85
|
+
authenticated local IPC
|
|
86
|
+
↓
|
|
87
|
+
GazeSight Desktop Runtime
|
|
88
|
+
↓
|
|
89
|
+
127.0.0.1:32147
|
|
90
|
+
↓
|
|
91
|
+
Firefox / Chrome
|
|
53
92
|
```
|
|
54
93
|
|
|
55
|
-
|
|
94
|
+
Desktop owns one long-lived Runtime and one browser bridge. Claude Code and Codex can connect through independent lightweight adapters at the same time. They share the same explicitly authorized browser target, and closing one adapter does not stop the other.
|
|
56
95
|
|
|
57
|
-
|
|
96
|
+
Desktop detects Firefox Release and Firefox Developer Edition separately without selecting either one automatically. Browser target selection still happens only through the extension.
|
|
58
97
|
|
|
59
|
-
|
|
98
|
+
The advanced standalone CLI mode is different: each MCP process owns its configured browser bridge. Two standalone processes cannot own the same port; the second exits with `GS_PORT_IN_USE`. Use Desktop shared-runtime mode for concurrent Claude Code and Codex sessions.
|
|
60
99
|
|
|
61
|
-
|
|
100
|
+
## MCP capabilities
|
|
62
101
|
|
|
63
|
-
|
|
102
|
+
GazeSight exposes exactly 25 public MCP tools, grouped around:
|
|
64
103
|
|
|
65
|
-
|
|
104
|
+
- viewport, region, element, full-page, FAST, and STABLE capture;
|
|
105
|
+
- DOM and element inspection;
|
|
106
|
+
- viewport measurement and responsive preview sizing;
|
|
107
|
+
- bounded click, type, key, hover, scroll, select, and focus interactions;
|
|
108
|
+
- console, network-failure, page-status, and error diagnostics;
|
|
109
|
+
- navigation and reload;
|
|
110
|
+
- temporary element highlighting;
|
|
111
|
+
- changed-region detection and visual diff.
|
|
66
112
|
|
|
67
|
-
|
|
113
|
+
Interactions use fixed, validated operations. GazeSight does not expose arbitrary page JavaScript evaluation.
|
|
68
114
|
|
|
69
|
-
|
|
70
|
-
|
|
115
|
+
## Visual Convergence — Beta
|
|
116
|
+
|
|
117
|
+
Visual Convergence helps an agent refine an implementation against a visual reference:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
Reference → Implement → Capture → Compare → Refine → Verify
|
|
71
121
|
```
|
|
72
122
|
|
|
73
|
-
|
|
123
|
+
The existing capture and `visual_diff` capabilities can compare equal-sized PNG images, localize differences, and maintain a local best-so-far checkpoint with an objective regression signal. The connected coding agent interprets the images and makes the code changes.
|
|
74
124
|
|
|
75
|
-
|
|
125
|
+
Visual Convergence does not guarantee pixel-perfect output, autonomous perfection, universal convergence, or regression-free implementation. Review the returned images and measurements as part of the development workflow.
|
|
76
126
|
|
|
77
|
-
|
|
127
|
+
## Privacy and security
|
|
128
|
+
|
|
129
|
+
- The browser bridge binds to loopback only.
|
|
130
|
+
- GazeSight does not operate a cloud capture backend.
|
|
131
|
+
- Screenshots and DOM content are not uploaded to a GazeSight server by default.
|
|
132
|
+
- Data returned through MCP may be processed by the connected coding agent or model provider according to that provider's settings.
|
|
133
|
+
- Only explicitly selected tabs are authorized.
|
|
134
|
+
- Pairing alone never authorizes a browser tab.
|
|
135
|
+
- No arbitrary page JavaScript execution is exposed.
|
|
136
|
+
- Credentials and pairing secrets should never be placed in commands, examples, or source control.
|
|
137
|
+
|
|
138
|
+
Read the full [GazeSight Privacy Policy](https://www.gazesight.dev/privacy/).
|
|
78
139
|
|
|
79
|
-
##
|
|
140
|
+
## Troubleshooting
|
|
80
141
|
|
|
81
|
-
|
|
142
|
+
### Desktop mode
|
|
143
|
+
|
|
144
|
+
- Open Desktop and check that Runtime is running.
|
|
145
|
+
- Check the Firefox/Chrome connection and active-target status.
|
|
146
|
+
- Use **Configure** or **Repair** for the Claude Code or Codex entry.
|
|
147
|
+
- If an adapter reports `GS_DESKTOP_RUNTIME_NOT_FOUND`, open GazeSight Desktop and retry.
|
|
148
|
+
- If the extension is connected but no target is authorized, open the intended tab and click **Use this tab**.
|
|
149
|
+
|
|
150
|
+
### Standalone CLI mode
|
|
82
151
|
|
|
83
152
|
```sh
|
|
84
|
-
|
|
85
|
-
npm run build
|
|
86
|
-
npm run lint
|
|
87
|
-
npm run typecheck
|
|
88
|
-
npm test
|
|
89
|
-
npm run extension:lint
|
|
90
|
-
npm run release
|
|
153
|
+
gazesight doctor
|
|
91
154
|
```
|
|
92
155
|
|
|
93
|
-
|
|
156
|
+
- `GS_PORT_IN_USE`: another standalone GazeSight MCP process owns that port. Stop it or use a separate configuration and port.
|
|
157
|
+
- `GS_NOT_CONNECTED`: check the extension connection and the configured loopback port.
|
|
158
|
+
- `GS_NO_TARGET_TAB`: select the intended browser tab with **Use this tab**.
|
|
159
|
+
- Use `gazesight pair` to pair another browser or recover after reinstalling an extension.
|
|
94
160
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
Published: https://www.npmjs.com/package/gazesight — first public release, `gazesight@0.3.5`, `latest` dist-tag. Published from a trusted local machine using a granular npm access token (bypass-2FA, revoked immediately after use; the account's normal interactive OTP/2FA prompt did not trigger reliably from the CLI in this environment). Root `package.json`'s `"private": true` guard was removed as the one deliberate, explicit step immediately preceding the real publish — never something a build/release script does automatically. Verified independently after publishing: `npm view gazesight@0.3.5` against the live registry, the published tarball downloaded and compared byte-for-byte (SHA-256) against the locally-built one, and a real `@modelcontextprotocol/client` connection through a fresh `npx --yes gazesight@0.3.5 mcp` confirming all 25 tools. For future releases, prefer npm's Trusted Publishing (OIDC from a GitHub Actions workflow, no long-lived token stored anywhere) if CI is set up for this project; otherwise a local publish with a short-lived granular token remains the fallback. Never commit an npm token to this repository. Verify any future publish from a clean environment:
|
|
161
|
+
## Uninstall the npm package
|
|
98
162
|
|
|
99
163
|
```sh
|
|
100
|
-
|
|
101
|
-
npx --yes gazesight@latest doctor
|
|
164
|
+
npm uninstall -g gazesight
|
|
102
165
|
```
|
|
103
166
|
|
|
104
|
-
|
|
167
|
+
Remove the `gazesight` MCP entry from the relevant coding agent if it is no longer needed. Do not remove unrelated MCP entries.
|
|
168
|
+
|
|
169
|
+
## Maintainers
|
|
105
170
|
|
|
106
|
-
|
|
171
|
+
```sh
|
|
172
|
+
npm ci
|
|
173
|
+
npm run build
|
|
174
|
+
npm run lint
|
|
175
|
+
npm run typecheck
|
|
176
|
+
npm test
|
|
177
|
+
```
|
|
107
178
|
|
|
108
|
-
|
|
179
|
+
Before an npm release, inspect the exact `npm pack` tarball and test it from a clean directory. Never commit npm tokens, browser-store credentials, signing certificates, or private configuration.
|
|
109
180
|
|
|
110
|
-
##
|
|
181
|
+
## License
|
|
111
182
|
|
|
112
|
-
|
|
183
|
+
GazeSight is proprietary software. All rights reserved. See [LICENSE](LICENSE).
|