Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs: point the project skills at the yarn commands

Shahriar4ded5343df60
diff --git a/.claude/skills/add-action/SKILL.md b/.claude/skills/add-action/SKILL.md
index 9ce7903..93ad1a1 100644
--- a/.claude/skills/add-action/SKILL.md
+++ b/.claude/skills/add-action/SKILL.md
@@ -28,7 +28,7 @@ That prints `✓ manifest publishes it as MCP tool "page_getAttribute"` and a **
node .claude/skills/add-action/new-action.mjs verify getAttribute
```
-`verify` runs `npm run compile` then builds and parses the bundled manifest, confirms your action is present, lists its params, and warns on any field missing a `.describe()`. Run it with no name to just re-check the whole registry (`node .claude/skills/add-action/new-action.mjs verify`).
+`verify` runs `yarn compile` then builds and parses the bundled manifest, confirms your action is present, lists its params, and warns on any field missing a `.describe()`. Run it with no name to just re-check the whole registry (`node .claude/skills/add-action/new-action.mjs verify`).
**Back out cleanly** (removes the file *and* unwires the registry):
@@ -68,14 +68,14 @@ Edit each, then re-run `verify`:
`verify` proves the tool is *published*; it does not load it into a running client. A `page_*` tool becomes callable in the real browser only after **both** sides are rebuilt and reloaded:
```sh
-npm run build && npm run mcp:build # rebuild extension + daemon from the new registry
+yarn build && yarn mcp:build # rebuild extension + daemon from the new registry
```
Then: reload the unpacked extension at `chrome://extensions` (Chrome does **not** auto-reload it), and **restart your MCP session** — MCP servers enumerate tools at session start, so a new tool won't appear mid-session. Check alignment with `node mcp/dist/cli.js status` → `manifest: in sync`; `DRIFTED` means one side wasn't rebuilt/reloaded. See the `voicelink` skill for driving the browser once it's live.
## Gotchas
-- **"Everything compiles" is not "it works."** A used top-level `document.x` type-checks fine (tsc has DOM types) and only blows up when the manifest bundle loads in Node. Always finish with `verify`, never just `npm run compile`.
+- **"Everything compiles" is not "it works."** A used top-level `document.x` type-checks fine (tsc has DOM types) and only blows up when the manifest bundle loads in Node. Always finish with `verify`, never just `yarn compile`.
- **The new tool is missing from the current session even after a rebuild.** Expected — restart the session. `verify`/`mcp:manifest` read the freshly-built bundle from disk, which is why they're the source of truth here, not your live tool list.
- **`create` refuses an existing file / already-imported name.** That's the guard against half-wired duplicates — pick another name or edit the existing module directly.
- **Don't hand-edit `dist/` or `.wxt/`** — both are generated; your action lives only in `lib/actions/`.
@@ -84,11 +84,11 @@ Then: reload the unpacked extension at `chrome://extensions` (Chrome does **not*
| Symptom | Cause | Fix |
| --- | --- | --- |
-| `verify` fails at `npm run compile` with an unused-variable error | The scaffold's `example` field/param is still unused after your edits | Use or delete it; the placeholder is meant to be replaced |
+| `verify` fails at `yarn compile` with an unused-variable error | The scaffold's `example` field/param is still unused after your edits | Use or delete it; the placeholder is meant to be replaced |
| `tool manifest failed … ReferenceError: document is not defined` | Top-level DOM access | Move it inside `execute()` |
| `does not survive the tool-name round trip` from `mcp:manifest` | Underscore in the action name | Rename to camelCase |
-| `status` shows `manifest: DRIFTED` | Extension and daemon built from different registries | `npm run build && npm run mcp:build`, reload the extension |
+| `status` shows `manifest: DRIFTED` | Extension and daemon built from different registries | `yarn build && yarn mcp:build`, reload the extension |
## The driver
-[`new-action.mjs`](new-action.mjs) — dependency-free Node, lives beside this file. Commands: `create <name> "<desc>"`, `verify [<name>]`, `remove <name>`, `docs`. It shells out to `npm run compile` and the MCP build, so run it from anywhere inside the repo.
+[`new-action.mjs`](new-action.mjs) — dependency-free Node, lives beside this file. Commands: `create <name> "<desc>"`, `verify [<name>]`, `remove <name>`, `docs`. It shells out to `yarn compile` and the MCP build, so run it from anywhere inside the repo.
diff --git a/.claude/skills/voicelink/SKILL.md b/.claude/skills/voicelink/SKILL.md
index 1634baa..d3db943 100644
--- a/.claude/skills/voicelink/SKILL.md
+++ b/.claude/skills/voicelink/SKILL.md
@@ -19,7 +19,7 @@ Call **`voicelink_status`** first. It is cheap and it is the only tool that expl
| `connected: false` | Browser not paired or not open | Tell the user to run `voicelink-mcp pair` and paste the code into the VoiceLink popup. Do not retry in a loop. |
| `connected: true`, `activeTab: null` | Paired, but the active tab hosts no content script (new tab, `chrome://`, web store) | `page_navigate` to an http(s) URL first — it works even there |
| `activeTab: {url, title}` | Ready | Proceed |
-| `manifestInSync: false` | Extension and CLI built from different registries | Rebuild both: `npm run build && npm run mcp:build`, then reload the extension |
+| `manifestInSync: false` | Extension and CLI built from different registries | Rebuild both: `yarn build && yarn mcp:build`, then reload the extension |
`voicelink_status` returns a `hint` field on failure — read it, it names the fix.
@@ -102,7 +102,7 @@ Useful commands: `voicelink-mcp status | pair | sessions | revoke | tools | logs
## 8. Adding a capability
-There are 17 page tools because there are 17 actions. To add one, write `lib/actions/page/<name>.ts` and add it to the array in `lib/actions/registry.ts` — that single edit publishes it as an MCP tool, because the daemon bundles the same registry. See `CLAUDE.md` for the load-bearing conventions (no top-level DOM, `.describe()` every field, no `.refine()`/`.transform()`, no underscores in action names). Verify with `npm run mcp:manifest`.
+There are 17 page tools because there are 17 actions. To add one, write `lib/actions/page/<name>.ts` and add it to the array in `lib/actions/registry.ts` — that single edit publishes it as an MCP tool, because the daemon bundles the same registry. See `CLAUDE.md` for the load-bearing conventions (no top-level DOM, `.describe()` every field, no `.refine()`/`.transform()`, no underscores in action names). Verify with `yarn mcp:manifest`.
## 9. The other driver: the in-extension agent
@@ -112,5 +112,5 @@ You (an external MCP client) are not the only thing that can drive this browser.
- **Runs are gated, you are not.** Agent-run invocations pass an approval gate (`requireApproval` in `~/.voicelink/config.json`) and appear on the user's timeline; direct MCP invocations do neither. Do not assume something the agent was denied is something you should do instead.
- **Skills live in `mcp/skills/*.md`**, with hand-written overrides in `~/.voicelink/skills/` and extension uploads in `~/voicelink/skills/`; all three are hot-reloaded per run and a later directory shadows an earlier one by name. Front-matter routes by trigger words; `@name` prefix forces one. A `category: site-exploration` skill is an overlay instead of a base — it stacks on top of the routed skill whenever the tab's host matches its `domains`. Skills load in two forms: flat `<name>.md` and `<name>/SKILL.md`. `voicelink-mcp skills` prints what the router can see.
- **Site maps are generated skills.** `@site-mapper map this site` runs a read-only, host-locked crawl that writes `<name>/SKILL.md` plus screenshots into `~/voicelink/skills/`, staged under `.staging/` until the user activates it in the panel. A mapping run refuses anything that changes a page (`MAPPING_READ_ONLY`), anything off the mapped host (`MAPPING_OFF_SITE`) and relative or history navigation; it is pinned to one tab (`MAPPING_TAB_CHANGED`). Mapping mode requires the explicit `@site-mapper` prefix — trigger words alone will not start one. When asked to change how the in-extension agent behaves, that markdown — not this file — is usually the place.
-- **Not every instruction becomes a run.** A local intent funnel (`lib/intent/`) scores each utterance first, and confident single-step commands — back, reload, scroll down, open github.com, press enter, click Sign in — run in the extension itself. Those never touch the daemon, so they leave no trace in `voicelink-mcp logs` and never appear as agent runs; on the user's timeline they carry a ⚡. If a user reports "it did the thing but nothing shows in the log", that is this, not a failure. `npm run intent:check -- "<what they said>"` explains any single routing decision.
+- **Not every instruction becomes a run.** A local intent funnel (`lib/intent/`) scores each utterance first, and confident single-step commands — back, reload, scroll down, open github.com, press enter, click Sign in — run in the extension itself. Those never touch the daemon, so they leave no trace in `voicelink-mcp logs` and never appear as agent runs; on the user's timeline they carry a ⚡. If a user reports "it did the thing but nothing shows in the log", that is this, not a failure. `yarn intent:check "<what they said>"` explains any single routing decision.
- **Debugging a run**: `NO_CLAUDE` means Claude Code is not on the daemon's PATH (set `claudeBin` in config.json); `RUN_IN_PROGRESS` means one instruction at a time; `RUN_INACTIVE` on a tool means the run was cancelled mid-call. Everything else lands in the daemon log.