# Julian Chrome Controller

A macOS Chrome extension, Native Messaging host, CLI, and MCP server for working with your existing Chrome profile. Read authorized task pages and act on fresh snapshots without moving your login data.

[中文说明](README.zh-CN.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

**Source available for noncommercial use.** [PolyForm Noncommercial 1.0.0](LICENSE) is not an OSI-approved open-source license. This release grants no commercial-use license, including business internal operations, commercial services/products, or resale; obtain a separate rights grant for such use. The standard license explicitly permits use by the organizations listed in its **Noncommercial Organizations** clause. The full license controls. Preserve [NOTICE](NOTICE) when redistributing. Copyright 2026 Julian Cooper.

## Features and requirements

- List existing tabs, claim task tabs, and open authorized URLs in background tabs.
- Read visible text and targets in the top document and open Shadow DOM.
- Click, fill ordinary fields, select native options, and scroll using snapshot IDs.
- Track session ownership, safeguard closing, reconnect locally, and report uncertain outcomes.

Requires macOS, Node.js 22+, npm, Git, Chrome 120+, and trusted local/MCP callers. Use a short stable checkout: the UTF-8 byte length of `<checkout>/runtime/control.sock` must be **less than 100**. There is no HTTP port, API key, or `.env` file.

## Quick start

```sh
mkdir -p ~/Projects
git clone https://github.com/Cooperiano/julian-chrome-controller.git ~/Projects/jcc
cd ~/Projects/jcc
./setup.sh
```

Default setup runs `npm ci --ignore-scripts` and prepares local configuration; it does not register a host with Chrome. Generated absolute-path configuration and runtime files are deliberately excluded from Git. To register this checkout:

```sh
./setup.sh --install
```

The installer refuses to overwrite registration pointing at another checkout. Preserve the existing installation and explicitly plan migration before changing it; do not delete the host to bypass this check. Moving this checkout requires regenerating local configuration and reviewing registration.

Open `chrome://extensions` in the intended profile, enable **Developer mode**, choose **Load unpacked**, and select the checkout's `extension` directory. Open the popup to check the connection. Load this extension in only one profile at a time.

The retained public key fixes extension ID `mmmkdojcghbmcbghbblndhlcmjfonkgd`; it is not a private signing key. Permissions are `tabs`, `scripting`, `nativeMessaging`, `storage`, `alarms`, and HTTP/HTTPS host access, for tab/page operations, local transport, ownership state, and connection maintenance. Incognito is disabled.

## Using with Codex

[AGENTS.md](AGENTS.md) provides development context. Inspect the generated `codex-mcp.toml` and merge its `[mcp_servers.julian_chrome]` block into your Codex configuration, preserving unrelated settings. Other stdio MCP clients can launch `node` with the absolute path to `src/mcp.mjs`.

There are 12 `chrome_*` tools. Each MCP process owns a session lease; exit releases claims and keeps tabs open. Tool availability in running clients depends on their configuration reload behavior. Verify a real connection by listing existing tabs and snapshotting an authorized task page. `health.version` and `snapshot.engineVersion` should be `0.2.0`. Popup status and mock tests alone do not prove live Chrome readiness.

## CLI and operation rules

```sh
node src/cli.mjs --help
node src/cli.mjs health
node src/cli.mjs tabs.list
```

Replace example `123` with a real authorized tab ID:

```sh
node src/cli.mjs tabs.claim '{"tabId":123}' task-session-001
node src/cli.mjs page.snapshot '{"tabId":123}' task-session-001
node src/cli.mjs tabs.release '{"tabId":123}' task-session-001
```

Use distinct session names per task, reuse them within a CLI task, and release claims when finished. Navigation/closing require the current `expectedUrl`; page actions require a fresh snapshot, and clicks/fills/selections require its target ID. `dispatched` means a DOM action was dispatched: read the page again to verify the result.

After timeout/disconnect, an action may have happened and its outcome may be `unknown`. Inspect the page before deciding what to do; never automatically repeat a mutation. Claims do not authorize purchases, publishing, messages, or other external effects.

## Limits and troubleshooting

Unsupported: iframe content, closed Shadow DOM, screenshots, file upload, native dialogs, and sites requiring trusted user-input events. Sensitive-field heuristics omit detected values and reject filling passwords, credentials, verification codes, and payment fields. They are not exhaustive redaction; ordinary text, URLs, titles, and fields can contain private data. Same-UID local processes and MCP clients are trusted; see [SECURITY.md](SECURITY.md).

For `CHROME_NOT_CONNECTED`, check registration, extension activation, profile, and checkout path. Reload the extension after source updates and read back both versions. The popup's reconnect control refreshes transport while keeping existing tabs. Pause access by disabling the extension in Chrome. No automatic upload or telemetry is implemented; your MCP client may process or retain returned data under its own policies.

## Development and references

```sh
npm ci --ignore-scripts
npm test
node src/install.mjs --prepare-only
```

There is no build step or lint script. Runtime code uses Node built-ins; tests use `jsdom` and simulated browser components to cover protocol, broker, Native Messaging, MCP, controller, popup, page actions, and installation. Passing tests does not replace live Chrome acceptance.

[browser-bridge](https://github.com/whg517/browser-bridge) was an architectural reference for the existing-profile extension/native-host split; no code was copied. See official [Chrome Native Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging) and [service worker lifecycle](https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle) documentation. Third-party dependencies retain their licenses, including the MIT-licensed `jsdom` development dependency.