# Chrome Actuator

Unofficial companion: drive the Chrome window you already have open from an agent
(tested with **Grok Build**). New work lands in a pink **Actuator** tab group in
the current session, not a new Chrome window.

```
tabs_create → snapshot → press @e12 / fill @e5 "text" → settle
```

v1 is an actuator, not a side-panel chatbot. The agent stays in the terminal.
The extension sees the page, assigns `@eN` refs, and clicks/types. Your cookies
and logins stay in Chrome.

**Not affiliated with, endorsed by, or sponsored by xAI.** "Grok" and "Grok
Build" are xAI marks, used here only to describe compatibility. See [NOTICE](NOTICE).

## Status

Phases 0–3 are in. `pnpm gauntlet` covers unit tests, the content-script
actuator, and a live Chromium tab driven through native messaging.

| Phase | What | State |
| --- | --- | --- |
| 0 | Workspace, stable extension id, side panel | done |
| 1 | Native messaging heartbeat | done |
| 2 | snapshot / press / fill on a real tab | done |
| 3 | Agent plugin + `/chrome` + skill | done |

## Load the extension

```bash
cd /path/to/chrome-actuator
pnpm install
pnpm --filter @chrome-actuator/extension build
```

1. Open `chrome://extensions`
2. Enable **Developer mode**
3. **Load unpacked** → `packages/extension/dist`
4. Pin the extension and click it (or `Cmd+Shift+G`)

Then register the native host (once) and fully quit Chrome:

```bash
node packages/host/dist/install.js
```

`--trust` on the plugin install lets the agent operate this Chrome profile.
Only do that if you trust the agent.

```bash
grok plugin install ./packages/plugin --trust
```

Side panel should say **connected** once the MCP host is running.

```bash
pnpm gauntlet   # unit + L3 + live native-messaging L4
```

Stable unpacked id (from the committed manifest `key`): `lgkcgenkjaalkfnpmglgpfclkaokblfj`

## Decisions we will not reopen

- Brain in the agent, body in Chrome. No in-extension LLM loop in v1.
- Native messaging, not WebSocket, not Playwright, not agent-device-the-binary.
- agent-device **contract** only (`snapshot` / `press` / `fill`).
- No `chrome.debugger` in v1 (no yellow infobar).
- Independent implementation. Do not copy another vendor's brand, marks, or
  reverse-engineered internals into this tree.

## Layout

```
packages/shared      protocol, snapshot grammar, target parser
packages/extension   MV3 side panel + service worker
packages/host        MCP + native host
packages/plugin      Grok Build plugin (compatibility layer)
```

## Tests

```bash
pnpm --filter @chrome-actuator/shared test
```

## License

MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).