Agent & Onboarding Reference

Ridealong is a Firefox extension that lets your local AI agent — Claude Code or Codex — drive your real, logged-in Firefox over MCP. There is no separate browser and no re-login: it's the session you already have, with the agent acting only inside the permission you grant, per tab, right now.

• Every tab is Off by default — until a mode is granted, every call is denied.
• The agent cannot change the permission mode — only the extension popup can.
• Effectful tools (click, fill, run_js) and navigate need an explicit tab id — no silent fall-back to whichever tab is active.
• Every brokered decision — allowed or denied — is written to a hash-chained audit log.

Instead of hand-registering an MCP server, the Ridealong popup mints a token and renders a single self-describing block. Paste it into Claude Code or Codex — the agent clones the repo, installs the bridge, and registers itself, using the token the extension already holds. Nothing is pasted back.

Ridealong is installed in this Firefox and wants you (the AI agent) to finish setup so you
can drive this browser over MCP. You are on the user's LOCAL machine (same machine as
Firefox). Please do the following, explaining each step to the user as you go:

1. Clone the repo if it isn't already present:
     git clone https://github.com/corleylun/ridealong.git
2. Install the bridge dependencies:
     cd ridealong/bridge && npm install
3. Register a stdio MCP server named "ridealong" that runs:
     node <ABSOLUTE_PATH>/ridealong/bridge/bridge.js
   with this environment variable set (do NOT change it — the extension already holds this
   exact token and will only connect to a bridge that uses it):
     FXMCP_TOKEN=9f2c7a1e6b2d4508af90c3e17b6d2a44c1e8b70d3f6a2951d84e0b7c62af1935
   - If you are Claude Code:
       claude mcp add ridealong --env FXMCP_TOKEN=9f2c7a1e6b2d4508af90c3e17b6d2a44c1e8b70d3f6a2951d84e0b7c62af1935 -- node <ABSOLUTE_PATH>/ridealong/bridge/bridge.js
   - If you are Codex (near-identical):
       codex mcp add ridealong --env FXMCP_TOKEN=9f2c7a1e6b2d4508af90c3e17b6d2a44c1e8b70d3f6a2951d84e0b7c62af1935 -- node <ABSOLUTE_PATH>/ridealong/bridge/bridge.js
4. Tell the user to RESTART you so the MCP server loads, then have them open the Ridealong
   popup in Firefox — it should show "connected".
5. Once connected: every tab is OFF by default. The user grants you a permission mode per
   tab from the popup (Read / Browse / Assist / Developer); effectful actions may need their
   approval. Full docs + troubleshooting: https://flowstations.net/ridealong/docs

Security note for the user: this makes your AI agent clone a repo, run npm install, and
register a local MCP server that can act in your logged-in Firefox — only within the per-tab
permission you grant, off by default, with a full audit log. Read the steps before running.

9f2c7a1e6b2d4508af90c3e17b6d2a44c1e8b70d3f6a2951d84e0b7c62af1935 above is a sample — your popup mints and embeds a different token for you. <ABSOLUTE_PATH> is filled in by the agent once it knows where it cloned the repo.

claude mcp add / a Codex config edit only take effect on the next agent session — the extension connects after you restart your agent, not instantly. Once it does, the popup turns green and every tab is still Off until you grant one.

An ordered ladder, set per tab by the user in the popup. A tool runs only if the tab's current mode is at least the tool's minimum — the agent can never raise its own level.

get_mode is read-only and off the ladder — it works even on an Off tab so the agent can report it has no access, but it can never change the mode.

Every call is relayed through the extension's broker; a call below the tab's mode is denied.

Every effectful tool — click, fill, andrun_js — requires approval. The agent invokes the tool, Ridealong opens a small trusted extension window (never an in-page overlay a hostile page could forge or click-jack) showing the concrete effect, and the call blocks until the user answers.

• Approve → the tool runs and the agent gets its normal result.
• Deny → the call fails. No answer within ~120s → the call fails closed, same as a deny.
• The user may enable per-tab auto-approve for click/fill — approved calls then run without a card, but are still audited. run_js always prompts regardless.
• Closing the approval window (not clicking Deny) resolves the call as a deny — a dismissed prompt never leaves the agent hanging.

The bridge binds a WebSocket server to 127.0.0.1:8765 only, and requires the shared token before it will relay any command. In the one-paste flow the extension mints the token and embeds it in the onboarding prompt, so the bridge is started already holding the value the extension expects — there's no separate paste-back step.

• Off by default. Connecting the agent never grants it anything — every tab still starts Off until a human raises it.
• Localhost only. The token is a local secret gating a loopback socket, not a boundary against other software running as the same user.
• Regenerate. The popup can mint a fresh token at any time; re-run the (updated) onboarding prompt to pick it up.
• Disconnect / Stop AI. Stop AI drops every tab to Off instantly; disconnect severs the agent's connection outright. Both are always available from the popup.

Every brokered decision — allowed or denied — is appended to a hash-chained log (~/.firefox-mcp/audit-log.jsonl when running through the bridge), so edits, deletions, or reordering are detectable after the fact.

{ seq, ts, tabId, tool, params (redacted), decision, reason, prevHash, hash }

fill logs the selector but never the value; run_js logs the full script.