Zamery Browser

Typed browser control for AI agents, built around explicit capabilities, semantic snapshots, and observable action outcomes.

Zamery Browser lets an agent work with a browser through a provider-neutral contract instead of coupling the agent to one automation engine. The Firefox provider connects to the user's already-running Firefox rather than launching a disposable browser profile.

Companion UI preview with synthetic example tabs; no private browser data is shown.

Install

npm install @zamery/browser-provider @zamery/pi-browser @zamery/browser-firefox

Node.js >=22.19.0 <25 is currently supported. @zamery/pi-browser is tested against @earendil-works/pi-coding-agent@0.87.1.

Packages

Architecture

AI / Pi agent                 Codex / local MCP host
     |                               |
@zamery/pi-browser            @zamery/browser-mcp
     |                               |
     +-- BrowserProvider V2 + optional interfaces --+
                         |
              @zamery/browser-firefox
                         |
         Native Messaging + signed companion
                         |
              Your existing Firefox

The provider contract is intentionally separate from the Firefox implementation. Another browser/provider can implement the same contract without changing the agent-facing tool layer.

Quick example

import { createBrowserProviderV2 } from "@zamery/browser-firefox";

const provider = createBrowserProviderV2();
try {
  const instances = await provider.listInstances();
  console.log(instances);
} finally {
  await provider.close();
}

For Pi integrations, @zamery/pi-browser exposes browser_status, browser_contexts, browser_snapshot, browser_assets, and browser_act. browser_assets returns opaque refs and safe metadata rather than source URLs or browser credentials.

Codex and other MCP hosts

@zamery/browser-mcp lets a local agent work in the Firefox you already use — logged in, no relaunch, no cookie export — on only the tabs or tab groups you choose to share, for a time you choose (this session, or 1–30 days). You can take over at any time; the agent can only ask to resume. See packages/browser-mcp, the security model and the evidence-backed release status.

Official MCP Registry: io.github.maemreyo/zamery-browser. Firefox Companion: AMO public listing.

Stable v0.2.4 uses @zamery/browser-provider@0.2.3, @zamery/browser-firefox@0.2.3, @zamery/browser-mcp@0.1.2, and @zamery/pi-browser@0.2.2, plus Mozilla-signed/public Firefox companion 0.2.6. Signed real-profile behavior and clean published-artifact acceptance both pass. See the release status for exact evidence.

Why this exists

Browser automation often hides important distinctions: whether the browser is user-owned, whether an action really happened, whether a DOM reference is still fresh, or whether a timeout occurred before or after mutation began. Zamery Browser keeps those boundaries explicit.

• The provider does not treat process success as browser authorization.
• Semantic snapshot refs are opaque and freshness-aware; they are not advertised as durable selectors.
• Actions preserve exact completed, not_started, partial, or unknown outcomes instead of converting ambiguity into success.
• Firefox actions are DOM-synthetic and are not represented as trusted OS input.
• Provider teardown does not imply ownership of the user's browser or tabs.
• Browser-backed asset discovery/transfer keeps sensitive source URLs and credentials provider-internal while exposing bounded opaque-ref workflows to consumers.

Firefox companion

The Firefox path uses a Mozilla-signed Zamery Browser Companion plus a Native Messaging host. Current signed companion 0.2.6 uses protocol 2. Protocol-1 0.1.x components remain incompatible and fail closed when mixed with protocol-2 components. See Firefox setup.

Documentation

• Getting started
• Architecture
• Firefox setup
• Security model
• Release status
• Codex + Firefox community roadmap
• Security policy
• Privacy policy
• Contributing
• Community support
• Code of Conduct
• Brand assets
• Community launch kit
• Examples

Project status

The npm packages are public under the @zamery scope and licensed under Apache-2.0. The API is still 0.x: additive work can land in minor releases, while intentional breaking changes are documented with migration notes rather than silently reinterpreting an existing protocol version.

License

Apache-2.0. Each package includes its own license file; the repository root license applies to the repository as a whole.