yoke-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamza Hamidi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MOTIVATION.md

@@ -0,0 +1,73 @@
+# What the bridge cannot do, and why yoke exists
+
+Observations of the Claude in Chrome extension and its MCP bridge (`claude --claude-in-chrome-mcp`), gathered while building [`claude-in-chrome-cli`](https://github.com/hamzahamidi/claude-in-chrome-cli) against it. Each entry says how it was established, because the interesting ones are counter-intuitive and several contradicted assumptions we started with.
+
+These are notes on fit, not a complaint. The bridge is built for an agent holding a conversation; most of what follows only bites a programmatic client, and a few are plain bugs worth reporting upstream.
+
+These measurements led to yoke, but yoke does not use that CLI or bridge. It is an independent Chrome extension and MCP server that works with any MCP client. Its local requirements are Node 22 or later and Chrome.
+
+## The tab group boundary
+
+**The bridge sees only tabs inside its own tab group.** A tab the user has open anywhere else is invisible, whatever window it is in. There is no move tool, no all-windows flag, and `select_browser` picks a browser rather than a tab. *Measured on one machine: the bridge could see 4 tabs while a session-file reader saw 29, of which 25 were outside the group.*
+
+**Nothing can adopt a tab.** Using a page the user already has open requires the human to move it in through Chrome's own tab context menu, then the client to notice. Our client does this by snapshotting group membership and watching for a stable single addition across two polls. *Measured: it works, and it takes a human gesture every time.*
+
+**No group API crosses the bridge.** Groups cannot be listed, named, recoloured or removed. Every group is titled `Claude (MCP)`, so once several exist they are indistinguishable. *Measured; upstream `anthropics/claude-code#86355` tracks the labelling half.*
+
+## Group lifetime
+
+**A group is lost permanently when its first tab closes.** Closing the group's oldest tab makes the bridge lose the entire group even while other tabs are still open in it. Those tabs then cannot be listed, driven or closed from any session, and the group's pill stays in the tab strip until a human removes it. *Measured in both directions: closing the second tab leaves the group intact and drivable; closing the first yields `Closed tab N. 1 tab(s) remain.` followed by `No MCP tab groups found`.*
+
+**A group dies with its last tab, so every create-and-close cycle makes a new one.** Two consecutive cycles produced group ids `528130259` then `339959904`; six cycles left six distinct group tokens in Chrome's session file. A client that tidies up after itself therefore accumulates one stranded pill per run unless it deliberately keeps a tab open forever. *Measured.*
+
+**Emptied groups are undetectable.** Chromium writes no group-lifecycle command to session data: group existence is only ever implied by a live tab's membership record. So an emptied group appears in no session snapshot and no API a client can reach. *Measured by diffing `Sessions/Session_*` around a known create-then-empty, which produced no group command at all, and confirmed across all three snapshots on disk.*
+
+**`tabs_create_mcp` requires a group to already exist.** With none, it refuses and points at `tabs_context_mcp`. Ordering that is not obvious, and easy to get wrong in a way that only shows up on a clean browser. *Measured: `No MCP tab group exists. Use tabs_context_mcp with createIfEmpty: true first to create one.`*
+
+## What comes back in a reply
+
+**Every reply embeds the full open-tab list, with titles and raw URLs.** Not just the tab being acted on: every tab in the group, appended to every single reply. For one of us that meant internal staging hostnames and a Slack workspace and channel id landing in ordinary command output, which a script will happily write to a log or a CI artifact. *Measured; it is why our demo recording elides that section.*
+
+**Replies carry `<system-reminder>` text addressed to a model.** Advice like preferring `browser_batch` arrives inside the tool result. Reasonable for an agent, noise in a data channel for a program. *Measured.*
+
+**Structured values arrive inside prose.** A new tab's id is only ever reported as `Created new tab. Tab ID: 2099042596`, so a client has to parse a sentence to learn it. This is the one place our client reads meaning out of prose rather than a field, and a wording change upstream would break it. *Measured.*
+
+**Reply shape is inconsistent for the same tool.** `tabs_context_mcp` answers with JSON when a group exists and with prose (`No MCP tab groups found…`) when none does, so a parser needs both paths. *Measured.*
+
+## Tool-level gaps
+
+**`navigate` reports success for a URL it did not visit.** Given `file:///path/to/x.html` it answered `Navigated to https://file:///path/to/x.html`: it had prefixed `https://` to the whole thing and gone to a bogus address, while reporting success. `data:` and `about:blank` are rejected outright with `Invalid URL`. *Measured; the silent mangling is the one we would call a bug.*
+
+**Screenshots are the page viewport only, and always JPEG.** Browser chrome is never captured, so the tab strip cannot be read; and the `computer` tool exposes no format option, returning JPEG whatever the caller intends to name the file. *Measured: a 1538x784 JPEG against a 1512x949 window, and the tool schema has no format parameter.*
+
+**A fresh tab cannot be scripted.** New tabs open on `chrome://newtab`, where `javascript_tool` answers `Cannot access a chrome:// URL`, so a client must navigate somewhere before it can evaluate anything. *Measured.*
+
+## Dependencies
+
+**The bridge needs the Claude Code CLI installed, and the extension signed in to the same account.** `cic` spawns `claude --claude-in-chrome-mcp`, and a mismatch surfaces as `Browser extension is not connected`. Reasonable for Claude Code users; a hard floor for anyone who only wants browser automation from a shell. *Measured.*
+
+This is a dependency of the bridge being measured, not a yoke dependency. yoke does not spawn Claude Code and does not require an Anthropic account or sign in. It needs Node 22 or later and Chrome.
+
+## What yoke changed
+
+The measurements supported building an independent extension and MCP server. The table records what that decision changed and what remains a browser limit:
+
+| Limitation | What yoke does |
+| --- | --- |
+| Tab group boundary | `chrome.tabs.query({})` sees every tab in every window. |
+| Nothing can adopt a tab | Every existing tab is addressable by explicit id, so adoption is no longer a separate operation. |
+| No group API | `chrome.tabGroups` lists groups, and yoke can group or ungroup named tabs. |
+| Group lost when its first tab closes | Group identity belongs to Chrome, and no tool addresses a tab through its group. |
+| Emptied groups undetectable | yoke queries Chrome's group state directly while a group exists. Emptying a group leaves its tabs open and removes the pill. |
+| Tab list in every reply | A tool returns the data for its own operation. It does not append the whole tab list. |
+| `<system-reminder>` in results | yoke adds no model-directed reminder text to tool results. |
+| Ids inside prose | The extension protocol carries ids as fields. MCP tool results are still concise text. |
+| `navigate` mangling non-http URLs | `navigate` and `open_tab` accept HTTP and HTTPS URLs and refuse other schemes without rewriting them. |
+| Screenshot format and chrome capture | PNG and JPEG are explicit options, and a background tab can be captured. Browser chrome remains out of reach. |
+| Needs Claude Code installed | yoke has no Claude Code dependency. Any MCP client can start `yoke mcp`. |
+
+The cost is equally plain. The extension requests `tabs`, `tabGroups`, `nativeMessaging`, `scripting` and `debugger`, plus `host_permissions: ["<all_urls>"]`. That is broad access to a signed in browser. Trusted input and background tab screenshots require `debugger`, which brings Chrome's visible debugging bar and prevents DevTools from sharing an attached tab. Page reading requires `scripting` and access across sites. yoke also owns the browser automation surface and the three process bridge that Chrome's native messaging rules require.
+
+That trade was accepted. The extension and MCP server in this repository are the result, and they stand on their own.
+
+The measurements and the smallest useful upstream requests are attached at `anthropics/claude-code#75901`.

package/README.md

@@ -0,0 +1,207 @@
+# yoke
+
+yoke lets an MCP client drive the Chrome profile you already use. It can work with every tab in every window, read pages, click and type, take screenshots, and inspect console and network activity. Your signed in sessions, cookies, extensions, and open tabs stay available.
+
+That is the reason to use yoke instead of starting a fresh browser through Playwright or Puppeteer. It works where you already work.
+
+Chrome requires a three part bridge:
+
+```text
+MCP client  <--stdio-->  yoke mcp server  <--Unix socket-->  native host  <--connectNative-->  Chrome extension
+```
+
+The MCP client starts `yoke mcp`. Chrome starts the native messaging host when the extension connects to it. The server reaches that host through a local socket. A client cannot connect straight to the extension because Chrome only gives native messaging connections to hosts that Chrome started.
+
+The project and repository are named `yoke`. The npm package is `yoke-mcp` because the bare package name belongs to an unrelated project. The command is `yoke`, and the extension is displayed as Yoke.
+
+## Why yoke exists
+
+yoke grew out of measurements of Anthropic's Claude in Chrome MCP bridge. That bridge could only see and act on tabs in its own managed group, and each reply included its full tab list with raw URLs. Those limits could not be fixed by an outside client. yoke addresses every tab by id and redacts URLs by default. [MOTIVATION.md](MOTIVATION.md) records the observations behind those choices.
+
+yoke is not affiliated with or endorsed by Anthropic or Google. It works with any client that speaks Model Context Protocol.
+
+## Install from source
+
+yoke is not on the Chrome Web Store. You must build it from source and load the extension unpacked.
+
+You need Node 22 or later and a Chromium based browser. The manifest requires Chrome 116 or later. Chrome, Chromium, Edge, and Brave registration paths are present. Only macOS has been exercised so far.
+
+### 1. Clone and build
+
+```sh
+git clone https://github.com/hamzahamidi/yoke.git
+cd yoke
+npm install
+npm run build
+node dist/cli.js install
+```
+
+Do not skip the build. `extension/manifest.json` loads `extension/browser/background.js`, and `extension/browser/` is generated output that is not stored in Git.
+
+`node dist/cli.js install` registers the native messaging host with each Chrome family browser it finds. If the `yoke` binary is already on your `PATH`, `yoke install` runs the same command.
+
+On Windows, `yoke install` does not complete registration. It prints a registry instruction instead of changing the registry. The Windows and Linux paths have not been tested yet.
+
+### 2. Load the extension
+
+In Chrome, Chromium, or Brave:
+
+1. Open `chrome://extensions`.
+2. Turn on Developer mode.
+3. Choose **Load unpacked**.
+4. Select the `extension/` directory inside the clone, not the repository root.
+
+In Edge, use `edge://extensions` and follow the same steps.
+
+The extension id must be `oceljemfocgfidhhdlbojkbkmlbfclna`. A public key in `extension/manifest.json` pins that id. The native host manifest allowlists it, so native messaging will refuse a build with a different id.
+
+The native messaging host id is `io.github.hamzahamidi.yoke`.
+
+### 3. Check every connection
+
+```sh
+node dist/cli.js doctor
+```
+
+When setup is complete, the last line is:
+
+```text
+Working. Every link in the chain answered.
+```
+
+If something is wrong, `doctor` stops after the first broken link, names it, and prints a suggested fix. It checks the compiled host, browser registration, local socket, extension reply, and whether tabs are visible.
+
+For a shorter connection check, run:
+
+```sh
+node dist/cli.js status
+```
+
+## Connect an MCP client
+
+An MCP client needs to start the command `yoke` with the argument `mcp`.
+
+If you want the binary from this checkout on your `PATH`, run this once from the repository:
+
+```sh
+npm link
+```
+
+A typical MCP server entry then looks like this:
+
+```json
+{
+  "mcpServers": {
+    "yoke": {
+      "command": "yoke",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Clients use different names and locations for their MCP configuration. If you do not want to run `npm link`, set the command to `node` and pass the absolute path to `dist/cli.js` before `mcp`.
+
+## What it can do
+
+yoke exposes 19 MCP tools. They are grouped here by the job they help with.
+
+| Job | Tools | What they do |
+| --- | --- | --- |
+| Work with tabs | `list_tabs`, `list_tab_groups`, `open_tab`, `navigate`, `close_tab`, `group_tabs`, `ungroup_tabs` | See every window, open background tabs, visit HTTP or HTTPS URLs, close tabs, and manage Chrome tab groups. |
+| Read a page | `get_page_text`, `read_page`, `find`, `screenshot` | Read visible text, describe interactive elements, find a matching element, or capture a foreground or background tab. |
+| Act on a page | `click`, `type_text`, `press_key`, `scroll`, `run_javascript` | Use trusted input by element reference, scroll the page, or evaluate JavaScript in the page's own world. |
+| Debug a page | `read_console`, `read_network`, `release_tab` | Read recorded console and network activity, then detach yoke and clear that tab's buffers. |
+
+Any tool that acts on an existing tab requires an explicit `tab_id` obtained from `list_tabs`. There is no active tab default. yoke never acts on whichever tab you happen to be viewing because no tab was named.
+
+`read_page` returns references such as `e1` for interactive elements. `click`, `type_text`, `press_key`, and reference based scrolling use those references. A reference expires when the page navigates or renders the element again, so call `read_page` again when a reference is stale.
+
+`navigate` and `open_tab` accept HTTP and HTTPS URLs. New tabs open in the background unless the caller asks to focus one.
+
+### Tab groups
+
+Every tab opened by yoke goes into a cyan group titled `yoke`, so the tab strip names what is driving those tabs. Pass `group_title` to `open_tab` for a different label, which is worth doing when more than one agent works in the same browser. The extension creates that group when needed and reuses a group with the same title in the same window. Reuse comes from Chrome's current group state, so it still works after Chrome has stopped and restarted the extension service worker. You do not collect a row of identical group pills.
+
+Tabs that were already open are never moved into this group. Grouping is visual only, so no tool depends on it to find a tab. `ungroup_tabs` removes tabs from their group without closing them. When the group becomes empty, Chrome removes its pill.
+
+### URL redaction
+
+yoke reduces URLs in tool output to origin and path by default. Query strings and fragments are omitted because they can contain session tokens or credentials. Non HTTP wrapper URLs are reduced to their scheme because their path can contain another full URL.
+
+`list_tabs` accepts `full_urls: true` when a caller needs raw URLs. The other tools that print URLs currently keep them redacted.
+
+## Permissions and access
+
+Installing Yoke gives a local MCP client broad control over the browser profile where you are signed in. It can read site content, run JavaScript, send trusted input, and observe network activity. That can include private accounts and private data. Install it only for MCP clients and agents you trust with that access.
+
+The extension requests these permissions:
+
+| Permission | What yoke uses it for | What the grant means |
+| --- | --- | --- |
+| `tabs` | List tabs in every window, including ids, titles, URLs, and group membership. Open, navigate, and close named tabs. | The extension can see which pages are open and can change the tab strip. |
+| `tabGroups` | List groups, create or reuse them, set their title and colour, and ungroup tabs. | The extension can inspect and change tab grouping in every window. |
+| `nativeMessaging` | Connect to the local host named `io.github.hamzahamidi.yoke`. | The extension can exchange data with a program installed on your computer. |
+| `scripting` | Inject the functions that read visible text, collect interactive elements, and resolve element references. | The extension can read and run code inside allowed pages. |
+| `debugger` | Use the DevTools Protocol for trusted clicks and typing, JavaScript evaluation, background tab screenshots, console messages, and network requests. | The extension gets deep control and inspection access on each tab it attaches to. |
+| `host_permissions: ["<all_urls>"]` | Let `scripting` work on ordinary sites regardless of host. | The site grant is broad. It is not limited to a list of sites chosen during installation. Per site permission is future work. |
+
+Chrome's own pages and the Chrome Web Store still block page script injection. yoke reports that restriction instead of returning an empty page.
+
+### Why the debugger permission is required
+
+An extension cannot create trusted input through page JavaScript. A click made by a content script reaches the page with `isTrusted: false`, and many sites ignore it. `chrome.debugger` is the extension route to `Input.dispatchMouseEvent`, which creates input the page cannot distinguish from a person's input.
+
+Chrome shows its "started debugging this browser" bar when yoke drives a tab. This is expected. Chrome also permits one debugger client per tab. A tab with DevTools open cannot be driven by yoke, and DevTools cannot open on a tab while yoke is attached. Call `release_tab` to detach yoke, remove the bar, and make the tab available to DevTools.
+
+The same permission lets `screenshot` capture a background tab. `chrome.tabs.captureVisibleTab` can only capture the active tab in a window.
+
+## Local connection and process lifetime
+
+The bridge does not open a TCP port. On macOS and Linux, the native host listens on a Unix socket inside a directory readable only by your user account. The socket itself is also restricted to that account. Windows uses a named pipe.
+
+Chrome owns the native host process. It starts the host when the extension calls `connectNative` and stops it when that connection closes. This is why the Unix socket between the MCP server and host is required.
+
+yoke has zero runtime dependencies. TypeScript and the Chrome type declarations are used only during the build.
+
+## Commands
+
+After `npm link`, the command surface is:
+
+| Command | Purpose |
+| --- | --- |
+| `yoke install` | Register the native messaging host with each detected Chrome family browser. |
+| `yoke doctor` | Check each link from the build through tab visibility and suggest the first fix. |
+| `yoke status` | Report whether the extension answers and print the local socket path. |
+| `yoke uninstall` | Remove the native host registration. |
+| `yoke mcp` | Run the MCP server over standard input and standard output. This is what an MCP client starts. |
+
+From a checkout that has not been linked, replace `yoke` with `node dist/cli.js` in these commands.
+
+## Current limits
+
+1. yoke is young and pre 1.0. Tool names, arguments, and results can change.
+2. Only macOS has been exercised. Linux and Windows install paths are written but untested. On Windows, `yoke install` prints a manual registry step but does not make the registry change.
+3. The project has one offline test file, `test/mcp-server.test.ts`. It checks the MCP surface and URL redaction, but this is not yet a well tested browser project.
+4. A driven tab shows Chrome's debugging bar and cannot share its debugger slot with DevTools.
+5. Element references expire after navigation or a page render. Console and network history starts when yoke first attaches to that tab, not before.
+6. Screenshots capture the page viewport, not browser chrome such as the address bar or tab strip.
+7. Chrome's internal pages and the Chrome Web Store cannot be read through the page tools.
+
+## Uninstall
+
+Remove the browser's native host registration with:
+
+```sh
+yoke uninstall
+```
+
+Then remove Yoke from the browser's extensions page. If you linked the checkout with npm, remove that link with:
+
+```sh
+npm unlink --global yoke-mcp
+```
+
+## License
+
+[MIT](LICENSE)

package/ROADMAP.md

@@ -0,0 +1,111 @@
+# Roadmap
+
+yoke is a Chrome extension and local MCP server for driving the browser you are already signed in to. It gives any MCP client one explicit interface to tabs, page content, trusted input, screenshots, console output and network activity, without a tab-group boundary or a second browser.
+
+This roadmap records what has been built and what comes next. Each release is small, shippable on its own, and the non-goals are part of the plan.
+
+It was originally written as four releases walking from reading the browser to driving it, one permission at a time. That is not what happened: all four landed together in one unreleased body of work. The sequence below has been rewritten to say what exists rather than what was planned, because a roadmap that disagrees with the manifest is worse than no roadmap. What the staged plan was protecting, a permission set a reviewer can follow, is now the job of v0.2.0.
+
+## Why this exists
+
+yoke exists because a useful browser tool should be able to work with the Chrome profile a person already uses, including every tab in every window. The measured bridge that preceded it could see only tabs inside its own group, offered no group API, and lost a group permanently when its first tab closed. [MOTIVATION.md](MOTIVATION.md) records the evidence, which is also attached upstream at `anthropics/claude-code#75901`.
+
+Tab groups are extension-only surface, proven by closing every alternative: page JavaScript sees a `chrome` object holding only `loadTimes, csi, app`; the DevTools Protocol has no tab-group surface across its 51 domains; Chrome's AppleScript dictionary has no group vocabulary. So the limitation is not something a client can work around. It has to be answered by an extension, which is this one.
+
+## Invariants
+
+Six rules hold across every release below.
+
+1. **No tab-group boundary, ever.** Every tab in every window is addressable. This is the reason the project exists, and a release that reintroduces a scope boundary has failed.
+2. **Permissions are earned, never requested speculatively.** Every permission in the manifest must be traceable to a tool that needs it, and the README must say what each one buys. This is the invariant the current tree comes closest to breaking: because reading and driving pages arrived in the same body of work, `scripting`, `debugger` and `host_permissions: ["<all_urls>"]` were all requested at once rather than one release at a time. Each is used by tools that exist, so the letter holds, but `<all_urls>` is broader than any single tool needs. Narrowing it is v0.2.0 and the first thing on the list.
+3. **MCP is the interface.** One implementation serves an agent and a shell script alike, so behaviour cannot diverge between them. A convenience CLI may wrap it; it never becomes a second implementation.
+4. **URLs are redacted by default.** Origin and path for http and https, bare scheme for anything else, and raw only on an explicit per-call opt-in. A tab listing is exactly where a session token gets copied into a log.
+5. **The extension never acts on a tab it was not told to.** No implicit current tab, no acting on the active tab because none was named.
+6. **Zero runtime dependencies.** TypeScript at build time, nothing shipped but the compiled output and the extension.
+
+One boundary is deliberately outside the sequence: this does not become a general-purpose scraping or automation farm. It drives the browser a human is signed in to, on that human's machine, which is the only thing it is good at and the only thing that justifies the permissions.
+
+## v0.1.0: read and drive the browser
+
+Theme: prove the thesis. Built, working end to end, not yet tagged or published.
+
+- TypeScript throughout, `strict` on, compiled to plain Node output with no runtime dependencies. Source in `src/`, extension in `extension/`, build to `dist/`.
+- The three-process shape: the extension connects to a native messaging host that Chrome spawns, the host owns a unix socket in a 0700 directory, and the MCP server connects to that socket. Chrome will only ever spawn the host itself, so this hop is not optional.
+- 19 MCP tools. Tabs and groups (`list_tabs`, `list_tab_groups`, `open_tab`, `navigate`, `close_tab`, `group_tabs`, `ungroup_tabs`), reading (`get_page_text`, `read_page`, `find`, `screenshot`), driving (`click`, `type_text`, `press_key`, `scroll`, `run_javascript`), and inspection (`read_console`, `read_network`, `release_tab`).
+- Trusted input through `chrome.debugger`, because an extension cannot dispatch it any other way: a synthesised event arrives with `isTrusted` false and many sites ignore it. Both consequences are documented rather than hidden: Chrome shows its debugging bar on a driven tab, and one debugger client per tab means DevTools cannot share it.
+- Elements are addressed by reference from `read_page`, never by coordinate, and a reference is re-resolved at the moment of use.
+- Tabs yoke opens join one reused group titled `yoke`, per window, created if absent. Tabs the user already had are never moved into it.
+- `yoke install` writes the host manifest for every Chromium-family browser present, `doctor` names the first broken link in the chain, `status` says whether the extension is connected, `mcp` runs the server on stdio.
+- The extension id is pinned by a key in its manifest, because native messaging allowlists by id and an unpacked load would otherwise get a fresh one each time. The private key never enters the repository, and CI asserts the key still derives the allowlisted id.
+- An icon, at 16, 32, 48 and 128, drawn on an 8 unit grid so every line lands on a pixel boundary at 16.
+- Offline tests for the MCP surface and the redaction, driven without a browser. CI green on Node 22 and 24 across Linux, macOS and Windows.
+
+The acceptance test is one number, and it holds: `list_tabs` returns every tab in the browser rather than the handful inside a managed group. On the machine this was built against that is 41 tabs, all of them addressable.
+
+Permissions as shipped: `tabs`, `tabGroups`, `nativeMessaging`, `scripting`, `debugger`, and `host_permissions: ["<all_urls>"]`.
+
+Non-goals that held: no publication, no recording, no macros, no scripting language. Composition belongs to the caller.
+
+### Promised in the original plan and not built
+
+Recorded here rather than quietly dropped, because each one is still wanted.
+
+- `focus_tab`, and moving a tab between windows.
+- `get_page_html`. `get_page_text` and `read_page` cover what callers actually asked for so far.
+- Form filling as its own operation: a native `select` cannot be driven by clicking, and a checkbox's state cannot be read back.
+- An explicit, revocable opt-in separating reading a page from driving one. Reading and driving are different grants and one grant currently covers both.
+
+## v0.2.0: ask for less
+
+Theme: the permission set becomes something a reviewer can follow, and yoke asks for less than the extension it replaces.
+
+- Move `<all_urls>` to `optional_host_permissions`, granted per site at the moment a tool first needs it. This is the release's whole point. An extension that drives a signed in browser earns trust by asking narrowly, and a community extension replacing a first-party one has to be strictly better on this axis or the argument for it is weak.
+- Separate the read grant from the drive grant, which the original v0.4.0 promised and did not deliver. Attaching the debugger is the moment to ask, not installation.
+- Every permission traced to the tools that need it, in a table in the README, with the failure mode stated for each one a user declines.
+- Anything unused comes out of the manifest.
+
+Non-goals: no new tools. A release that narrows permissions and adds surface at the same time cannot be reviewed.
+
+## v0.3.0: the gaps
+
+Theme: the operations a caller currently has to work around, and the ones with no workaround at all.
+
+- `form_input`: set a `select`, read a checkbox back, drive a native control that a click cannot reach.
+- `file_upload` through `DOM.setFileInputFiles`. Clicking a file input opens an OS picker nothing can dismiss, so there is no substitute for this one.
+- The four items from the list above: `focus_tab`, moving a tab between windows, `get_page_html`, and the separated grants if 0.2.0 leaves them.
+- `press_key` past its eight named keys, with modifiers. Back and forward. Hover.
+- Elements inside a shadow root, which the snapshot cannot currently see.
+- `read_console` and `read_network` print the `url` and `line` they already collect.
+
+Non-goals: still no recording or macros.
+
+## v0.4.0: publication
+
+Theme: installable by someone who is not us.
+
+- Chrome Web Store listing, with the privacy policy and permission justifications that `debugger` and host access will be asked to defend. Review is typically days and can be weeks, so publication keeps its own release clock.
+- Reproducible build from a tagged commit, so the published bundle can be checked against source. An extension asking for these permissions has to be auditable, and "trust the listing" is not auditable.
+- Verify the store honours the pinned `key`, so the published id matches the one the native messaging manifest allowlists. If it does not, the host registration points at the wrong id and nothing connects, which is worth finding before shipping.
+- npm publish of `yoke-mcp`, which has not happened yet.
+
+## v0.5.x: stabilisation
+
+Bug fixes only. Soak the debugger path, decide whether Windows is supported and either finish it or say so, and leave the tool names alone.
+
+## v1.0.0: the contract release
+
+1. Frozen tool names, arguments and result shapes. Changing one after 1.0 requires a major bump.
+2. Three-platform CI green, including the native messaging install path rather than only the build.
+3. A week of the maintainer's real use without an orphaned host process, a stuck socket or a lost group.
+4. Every permission in the manifest traceable to a tool that needs it, and none broader than that tool requires.
+5. Zero known cases where a raw URL, a password, or any other value a caller did not ask for escapes into output.
+
+## Decisions
+
+**Project identity.** The name is `yoke`. Nothing in the project is specific to one vendor's assistant, so the old vendor-specific framing described the history rather than the software. Google's brand guidance reserves "Chrome" for Google's own products, which also made the previous `chrome-live` code name a poor choice for a possible store listing. The repository and project are `yoke`, the npm package is `yoke-mcp` because the bare package name was taken, the binary is `yoke`, the extension display name is `Yoke`, and the native messaging host id is `io.github.hamzahamidi.yoke`.
+
+## Open decisions
+
+Recorded rather than guessed at, because they are not implementation details.
+
+**Whether browser operations get direct CLI commands.** The `yoke` binary already owns installation, diagnosis, status, removal and the MCP server entry point. MCP remains the browser interface. The open question is whether thin shell commands should expose those same operations for cron jobs and shell pipelines. Invariant 3 permits a wrapper, but not a second implementation.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// The one command: register the native host, check the connection, or run the
+// MCP server. Everything else this project does is a tool call.
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { install, uninstall } from './install.js';
+import { endpointPath } from './socket-path.js';
+const USAGE = `yoke - browser automation in the Chrome you are already signed in to.
+
+Usage:
+  yoke install     register the native messaging host with your browsers
+  yoke doctor      check every link in the chain and say which one is broken
+  yoke status      is the extension connected?
+  yoke uninstall   remove the host registration
+  yoke mcp         run the MCP server on stdio (what an MCP client spawns)
+
+Getting set up, once:
+  1. npm run build
+  2. yoke install
+  3. load extension/ at chrome://extensions with Developer mode on
+  4. yoke doctor            -> says which link is broken, if any
+  5. register the server with your MCP client:
+       command: yoke
+       args:    ["mcp"]
+`;
+const EXIT = { OK: 0, UNAVAILABLE: 3, USAGE: 64 };
+async function main() {
+    const action = process.argv[2];
+    if (action === 'mcp') {
+        // Hands over to the server, which owns stdio from here on.
+        const { main: serve } = await import('./mcp-server.js');
+        serve();
+        return EXIT.OK;
+    }
+    if (action === 'install') {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const result = install({ hostPath: join(here, 'native-host.js') });
+        for (const [browser, file] of result.written) {
+            process.stdout.write(`registered for ${browser}: ${file}\n`);
+        }
+        for (const [browser, reason] of result.skipped) {
+            process.stderr.write(`skipped ${browser}: ${reason}\n`);
+        }
+        if (result.platform === 'win32') {
+            process.stdout.write('On Windows the host is declared in the registry rather than on disk. '
+                + `Add a REG_SZ default value under HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${result.hostName} `
+                + 'pointing at the manifest file.\n');
+            return EXIT.OK;
+        }
+        if (result.written.length === 0) {
+            return EXIT.UNAVAILABLE;
+        }
+        process.stdout.write('\nNow load extension/ at chrome://extensions with Developer mode on.\n');
+        process.stdout.write(`It has to keep the id ${result.extensionId}, which the pinned key in its manifest guarantees.\n`);
+        return EXIT.OK;
+    }
+    if (action === 'uninstall') {
+        const { removed } = uninstall();
+        for (const [browser, file] of removed) {
+            process.stdout.write(`removed for ${browser}: ${file}\n`);
+        }
+        if (removed.length === 0) {
+            process.stdout.write('nothing was registered\n');
+        }
+        return EXIT.OK;
+    }
+    if (action === 'doctor') {
+        const { doctor, render } = await import('./doctor.js');
+        const checks = await doctor();
+        process.stdout.write(render(checks));
+        return checks.every((check) => check.ok) ? EXIT.OK : EXIT.UNAVAILABLE;
+    }
+    if (action === 'status') {
+        const { available } = await import('./socket-client.js');
+        const reachable = await available();
+        process.stdout.write(`extension: ${reachable ? 'connected' : 'not reachable'}\n`);
+        process.stdout.write(`socket: ${endpointPath()}\n`);
+        if (!reachable) {
+            process.stdout.write('\nIf install has run and the extension is loaded, open chrome://extensions and '
+                + 'check its service worker is running. Chrome starts the host on demand.\n');
+        }
+        return reachable ? EXIT.OK : EXIT.UNAVAILABLE;
+    }
+    process.stdout.write(USAGE);
+    return action === undefined || action === '-h' || action === '--help' ? EXIT.OK : EXIT.USAGE;
+}
+main()
+    .then((code) => { process.exitCode = code; })
+    .catch((failure) => {
+    process.stderr.write(`yoke: ${failure instanceof Error ? failure.message : String(failure)}\n`);
+    process.exitCode = EXIT.UNAVAILABLE;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/doctor.d.ts

@@ -0,0 +1,10 @@
+export interface Check {
+    ok: boolean;
+    label: string;
+    detail: string;
+    /** What to do about it, when there is something to do. */
+    fix?: string;
+}
+/** Runs the checks in order, stopping the remote ones once a local one fails. */
+export declare function doctor(): Promise<Check[]>;
+export declare function render(checks: Check[]): string;