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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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.mdindex 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.mdindex 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.