Content
# opencode-windows-chrome
Native Windows helpers and an OpenCode skill for explicitly requested access to a visible Chrome instance through loopback CDP. This is a copy-based integration, not an npm package, and it requires no administrator access.
## Prerequisites
| Component | Requirement |
| --- | --- |
| Operating system | Windows 10 or Windows 11 |
| OpenCode | A current OpenCode installation |
| OMO | Minimum and recommended: oh-my-openagent v4.11.0+ with skill MCP lifecycle fixes |
| Chrome | Chrome 136 or later |
| Node.js | Node.js 18 or later, including npm/npx |
| Shell | Windows PowerShell 5.1 or later |
Official references: [Chrome remote debugging](https://developer.chrome.com/docs/devtools/remote-debugging/), [Node.js](https://nodejs.org/), and [PowerShell](https://learn.microsoft.com/powershell/).
## Architecture and security
`Start-WindowsChrome.ps1` starts Chrome with a dedicated profile at `%LOCALAPPDATA%\opencode-windows-chrome\profile` and binds CDP only to `127.0.0.1:9222`. `Test-WindowsChrome.ps1` queries only the CDP version endpoint and does not display the WebSocket token. `Show-WindowsChrome.ps1` makes a best-effort focus request only after validating the loopback Chrome listener.
The sibling `mcp.json` is OMO Skill-Embedded MCP support, not native OpenCode skill behavior. It pins `@playwright/mcp@0.0.78`; npx -y can download that pinned package and its runtime transitive dependencies when the MCP starts.
The dedicated profile is mandatory. Do not use Chrome's default profile for this integration. CDP controls the profile it serves, so keep it loopback-only and avoid placing secrets in the dedicated profile. See [SECURITY.md](SECURITY.md).
## Install, update, and uninstall
From a checkout of this repository, copy the complete skill directory with the installer. It stages and validates the replacement, preserves the prior skill on failure, and does not mutate any OpenCode configuration file.
```powershell
# Global: %USERPROFILE%\.config\opencode\skills\windows-chrome
.\scripts\Install-WindowsChromeSkill.ps1 -Scope Global
# Project: <project>\.opencode\skills\windows-chrome
.\scripts\Install-WindowsChromeSkill.ps1 -Scope Project -ProjectRoot C:\src\my-project
```
To update, run the same copy command from a newer checkout. Restart OpenCode after install or update so it reloads the skill/MCP lifecycle. To uninstall, remove only the installed `windows-chrome` directory from the chosen global or project skill destination. No administrator access is required.
If `npx` is not found, ensure Node.js is on `PATH`; when launching manually, use the Node-provided `npx.cmd`. The MCP file deliberately remains configured with `npx` so OpenCode controls the usual MCP lifecycle.
## Startup, status, and focus
```powershell
# Start the dedicated-profile instance, or reuse only a verified listener.
.\scripts\Start-WindowsChrome.ps1
# Query only the CDP version endpoint.
.\scripts\Test-WindowsChrome.ps1
# Best-effort restore/focus of the verified Chrome listener owner.
.\scripts\Show-WindowsChrome.ps1
```
All v1 helpers are fixed to port `9222`, matching the installed MCP endpoint. A non-9222 port can only diagnose or start a browser that the installed `mcp.json` will not connect to unless a user manually adapts their repository copy; v1 therefore rejects it. Side-effecting helpers support `-WhatIf`, refuse unverified listeners, and never terminate Chrome.
## Using the skill
Use prompts such as “Use the existing visible Windows Chrome session to open a new tab” or “Connect through CDP port 9222 and inspect the page I identify.” The `windows-chrome` skill is selected only for explicit Windows Chrome/CDP requests. Ordinary or ambiguous browser requests remain on the default OMO Playwright routing; this skill does not fall back to it when its endpoint is unavailable.
## Troubleshooting and release checklist
- Run `Test-WindowsChrome.ps1` first. A healthy result identifies `Chrome/` at the loopback version endpoint without displaying a WebSocket token.
- If OpenCode reports a manager disposed error, fully restart OpenCode and use OMO v4.11.0+.
- For a native Windows release smoke test, run install with `-WhatIf`, start the dedicated profile, run status, request focus, then confirm the default Chrome profile was not used. Do not run this against user browsing data.
- CI validates static contracts and Pester on Windows but does not launch Chrome.
- See [docs/troubleshooting.md](docs/troubleshooting.md) before publishing a source release.
### Release checklist
1. Run `python tests/static_validate.py` and the Windows Pester suite.
2. Verify the installed MCP remains pinned to `@playwright/mcp@0.0.78` and loopback port 9222.
3. Complete the native Windows smoke test above using the dedicated profile only.
4. Confirm CI did not launch a browser or upload browser/profile artifacts.
5. Verify and update immutable action commit SHAs only against the official action repositories, as described in [SECURITY.md](SECURITY.md).
6. Verify CI downloads Pester 5.5.0 from the official Gallery URL and checks its documented size, SHA-256, and official Gallery OData SHA-512 metadata before import.
## Compatibility
| Scenario | Status |
| --- | --- |
| Dedicated Chrome profile on Windows 10/11 | Supported |
| Default Chrome profile | Not supported |
| Loopback CDP on port 9222 | Supported |
| LAN or remote CDP endpoint | Not supported |
| Automatic Chrome install or port selection | Not supported |
