Clickable prototype in 48h
AI & integrations

Browser extension connector

A Chrome extension that connects a web service with no public API to your own app: it reads the site's own traffic from the signed-in browser, replays its auth only to that site, buffers offline and syncs through one polled endpoint.

Repository
timerise-ai/browser-extension-connector
Released
September 28, 2026
Build it with TimeriseBuild it yourself
npx skills add timerise-ai/browser-extension-connector
v0.1.5
Current release
18
Reference docs
6
Non-negotiables
MIT
License

The problem

What problem does Browser extension connector solve?

Some of the services a business depends on have no API, no OAuth and no export. A marketplace seller panel, a carrier portal, a supplier's ordering site. The data is there, on screen, for a signed-in user. Getting it into your own system usually means someone retyping it, or a scraper that holds the user's password.

There is a third way. The user's browser already sees every response the site serves. A Chrome extension can read that traffic in the page's own context, replay the page's own auth headers for pulls and writes, and hand the result to your app. No password leaves the browser, and the site sees the same session it always did.

The hard part is not the tap. It is the runtime: a service worker Chrome evicts after thirty seconds, alarms that fire at most once a minute, a network that comes and goes. This skill gives a coding agent the connector built for that runtime, with a bounded offline buffer, one polled endpoint carrying records up and commands down, PIN pairing and diagnostics. The service itself sits behind an adapter seam, so one connector serves many sites.

The module

What does the skill build?

An agent with this skill builds one module as a Chrome MV3 extension that syncs with your app, on your stack. For Browser extension connector that module consists of:

  • 1. A MAIN-world tap on the page's own fetch and XHR
  • 2. Auth headers replayed only to their own origin
  • 3. A bounded offline buffer
  • 4. One polled endpoint carrying records up and commands down
  • 5. PIN pairing
  • 6. Diagnostics

What it needs from you

  • Chrome 120 or newer. world: "MAIN" in a declared content script is the whole basis of the tap.
  • Node with `esbuild`, plus typescript and vitest for the checks. Nothing else: the build is five bundles in two formats and a zip written with node:zlib.
  • A host app that answers two endpoints, pair and sync, to `references/server-contract.md`. Anything that can serve JSON will do.
  • One adapter per service, written against `references/adapter-seam.md` as its own skill. The tree builds and boots with the shipped stub, and syncs nothing until an adapter is wired.

Provenance

Where do the rules come from?

This skill was written by the engineer who has shipped this module. The earlier implementation it was audited against was a connector extension carrying one service's data into a host app, with an architecture note kept alongside it recording every incident. The templates hold the properties a connector has to hold: every response from the host handled the same way, so a command handed out on any post runs; every live relay port kept, so two open tabs are two ports; acks riding the next post, so a browser closing mid-command loses nothing; a buffer that is bounded, drops oldest and reports the drop; records validated one by one, so one bad record cannot wedge the channel; and a credential read only from the page's own requests, replayed only to the origin it came from, never persisted and never posted to the host. The suites and the build state each one, and `references/provenance.md` has the record.

The engineering ledger for this skill: what the audit of the earlier implementation changed and how the templates verify it, what was kept deliberately and why it is safe, and what was designed here and has never run in production. Audited on 2026-09-16 against a connector extension that had been carrying one service's data into a host app for months, with an architecture note kept alongside it recording every incident. The service adapter, the host's own vocabulary and the server implementation stayed behind; the runtime, the seam and the hardening travelled.

The ledger separates what the audit changed, what was kept on purpose, and what has not run in production yet.

  1. Fixed in the templates

    • A progress-only post discarded the commands it was handed The pull step posted a second request per tick carrying only cursor progress, and ignored that response. The host claims commands under a lease on every post, so any command that became due between the two posts was leased, had its attempt counter incremented, and never ran. Past the attempt cap it was marked failed without ever having executed, while the browser looked healthy. Confirmed by reading the host's sync handler and its claim function. Shipped: one exchange() path for every post and handleResponse() for every answer, see sync-engine.md; pinned by engine.test.ts.
    • Two service tabs, one port slot The worker kept only the most recently connected relay port. Closing the newer tab nulled the slot while the older tab's port was alive; every pull and command then failed "no service tab" and the loop fell to the slow cadence until a tab was reopened. Shipped: PortRegistry, see service-worker-loop.md; pinned by ports.test.ts.
    • Batch ids were minted per attempt The comment promised a retried post would be recognisable in the host's log; the id was Date.now() per attempt, so it never was, and two batches in one millisecond would have collided. Shipped: an id keyed on the batch's content plus a sequence, see sync-engine.md; pinned by engine.test.ts.
    • Every user-facing string was a literal, in one language Options page, popup, diagnostics and worker error messages were written inline in the team's own language, including the strings that travel to the host in error. Shipped: strings.ts with keys and English defaults, see popup-and-strings.md.
    • Small: the body size cap counted characters and was named as bytes Renamed MAX_BODY_CHARS; behaviour unchanged.
Read the full record in provenance.md

Non-negotiables

What are the 6 rules the module never breaks?

Every module built from this skill holds these, whoever builds it. The same list is in the skill's README and SKILL.md, so the agent reads it before it writes a line.

  1. Never create the alarm unconditionally at startup.

    chrome.alarms.create replaces and restarts a same-named alarm, so a worker that is revived often pushes its own next fire away and never polls. Check alarms.get first, and poll immediately on bootstrap.

  2. Never fall back to a worker-side fetch when no service tab is open.

    The worker holds no session with the service, so a login page comes back, parses as zero rows, and looks exactly like a finished pull. Refusing is what makes the failure visible on the connection card.

  3. Never keep one "current port".

    Two open tabs are two relay ports, and closing the newer one must not orphan the older. PortRegistry keeps them all and ports.test.ts pins the rule.

  4. Never acknowledge a command on the same post that ran it.

    Acks ride the next post, so a browser that closes in between lets the lease expire and the command comes back instead of being lost. Three cases in engine.test.ts cover the ack path, including a post that gets no answer.

  5. Never validate a batch as a whole on the host.

    One bad record must cost one record, named in rejected; a batch-level 400 keeps the whole buffer re-posting forever while the card still says connected.

  6. Never write into the service until the write path is verified live

    , and never delete by anything but the id the service returned. writeVerified gates every writing command, and a create that returns no id throws rather than leaving something only a human can remove.

Fit

When should you use it, and when not?

Use it for

  • Building or hardening an extension that connects a third-party site to your own app, where the site offers no partner API and handing over the user's password is not acceptable. The service is the seam; this skill is the infrastructure under any service adapter.

Not for

  • A service with a partner API, OAuth or an exportInsteadThat API. A connector is a workaround with real costs, and this skill says so before it starts
  • Server-side scraping with the user's stored passwordInsteadNothing here. It is a different threat model, it works from anywhere forever, and it usually breaks the service's terms
  • A one-off data exportInsteadA script pasted into DevTools, which is cheaper than an extension and stops existing afterwards
  • One service's parsers, endpoints and quirksInsteadAn adapter skill on top of this one, written against references/adapter-seam.md
  • The host's routes, staging tables, merge queues and console UIInsteadThe host's own idiom, to the contract in references/server-contract.md and the operator surface in references/operations.md
  • Recording how employees work, for SOPs or automation scopingInsteadThe sibling `ecommerce-process-mining` skill, which captures consented DOM events from the tools staff already use; this one carries a service's data, not a record of the work
  • Pairing and running unattended screens in a venueInstead`digital-signage`, which pairs displays by PIN and plays to them

Build it yourself

How do I install it?

One command. The skills.sh CLI installs the skill into every skills-compatible agent it finds.

$ npx skills add timerise-ai/browser-extension-connector

Claude Code

Invoke with /browser-extension-connector

Codex CLI

Invoke with $browser-extension-connector

Gemini CLI

Invoke with /skills

Name the agents instead with -a, for example npx skills add timerise-ai/browser-extension-connector -a claude-code -a codex. Or clone the repository into your agent's skills folder. Nothing in it is agent-specific.

What is inside the repository (26 entries)
  • SKILL.mdEntry point: architecture diagram, six critical facts, six hard rules, quick start, and the reference directory
  • README.mdThis front door
  • CHANGELOG.mdKeep a Changelog, one section per release, newest first
  • CLAUDE.mdWhat this repository is and the conventions for editing the skill itself
  • LICENSEMIT
  • references/adaptation.mdThe seam contract with the host app: record, pull and command kinds, the host probe, the rename table, the order of work
  • references/architecture.mdThe three execution contexts and why each exists, the credential rules, why it polls, the honest ceiling on the cadence
  • references/manifest-and-permissions.mdThe manifest, every permission with its rationale, what is deliberately absent, single purpose, Web Store versus self-hosted
  • references/main-world-tap.mdThe MAIN-world tap: patching the page's fetch and XHR, what it captures, the header fingerprint, config injected at build time
  • references/relay.mdThe relay: port and keepalive ping, replaying the page's own auth headers, orphaned contexts, the cross-context message contract
  • references/service-worker-loop.mdWorker plumbing: the alarm that must not be recreated, the port registry, bootstrap, message routing, constants
  • references/sync-engine.mdThe loop's logic: the behaviour contract, one exchange path for every post, commands, acks, the pull step, backoff
  • references/offline-queue.mdThe bounded buffer, the serial lane, and routing records to the pairing bound to their account
  • references/host-client.mdThe host client, the four failure classes, stored pairings and last-post state
  • references/diagnostics.mdThe test-connection ladder, run as a real poll, and what each rung tells the user
  • references/server-contract.mdWhat the host must implement: the wire types, the pair and sync endpoints, directives, health, retention
  • references/adapter-seam.mdThe ConnectorAdapter seam a per-service adapter fills, the rules it must keep, the stub and the registry
  • references/pairing-ui.mdThe options page: the PIN flow, the origin permission request, test connection, unpair
  • references/popup-and-strings.mdThe read-only popup and the strings map every user-facing literal goes through
  • references/build-and-package.mdesbuild with two formats, the deterministic zip, chrome.d.ts, the tsconfig, the release order
  • references/tests.mdThe ten suites, 76 tests, what each one pins, and how to test an adapter
  • references/operations.mdThe runbook: what the host must show per connection, silence, kill switch, extension reloads
  • references/provenance.mdThe engineering ledger: what the audit of the earlier implementation changed and how the templates verify it, what was kept deliberately, and what is new in the skill
  • assets/extension/The runnable extension tree the references quote: sources, the hand-written chrome.d.ts, the build and pack scripts, and the ten test suites
  • evals/The prompts an operator types after installing (prompts.md) and one file per agent eval: the skill installed into an empty Next.js app, one prompt, no help, then type-checked, built and tested
  • .github/workflows/agent-eval.ymlThe caller of the index's eval workflow, copied verbatim from the standard: prompt 1 in Claude Code, Codex CLI and Gemini CLI on every published release, any prompt on a maintainer's dispatch

Recent releases

  1. v0.1.5September 28, 2026

    Wording release, from scoring the prompt-1 agent eval runs against 0.1.4. The templates are unchanged.

  2. v0.1.4September 28, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.3. Connectors built from an earlier version should copy in src/inject/net-tap.ts, src/background/ports.ts, src/background/queue.ts, src/background/engine.ts and src/background/index.ts, and the three test files that pin them.

  3. v0.1.3September 28, 2026

    Documentation release. The skill content is unchanged from 0.1.2.

SKILL.md README.md CHANGELOG.md

After installing

What do I tell my agent?

Say what you need in your own words; the skill supplies the how. These are starting points, and the ones we tested say how it went.

  1. Build a Chrome extension that pulls our orders from a supplier portal with no API, from the user's signed-in session, and sends them to our app.

    Chrome MV3Gemini CLIBuilt, checks passCodex CLIBuilt, checks passClaude CodeBuilt, checks pass

  2. Our extension's service worker dies and records go missing. Make the sync reliable with an offline buffer and a single polled endpoint.

    Chrome MV3

  3. Pair the extension with a user's account in our app using a PIN, instead of asking for their password.

    Chrome MV3

Tested

How does it do in each agent?

We install the skill into an empty Next.js app, give the agent one of the prompts above and no further help, then type-check, build and run the tests it left behind. Nothing is fixed by hand before the checks, and a failing run is published like a passing one. The procedure and every result are public, and the first prompt runs again before each release.

  • Gemini CLI0.61.0

    gemini-3.8-flash

    Built, checks pass
    Build a Chrome extension that pulls our orders from a supplier portal with no API, from the user's signed-in session, and sends them to our app.
    Typecheck: passBuild: passTests: pass
    Time
    7 min
    Changed
    64 files, +9,258 lines
    Stack
    Chrome MV3
    Skill
    v0.1.5
    Run
    Sep 28, 2026

    Result fileAgent log

    What we saw

    Rubric 8/8, scored from the summary. Adapter wired through tap-config.ts, ADAPTERS and PROVIDER; header auth with credentials: "omit" and minimal permissions; the 76 shipped tests pass unmodified; PIN and pepper from the environment with no defaults, blank in .env.example; all three handover points in the final message.

  • Codex CLIcodex-cli 0.158.0

    gpt-6-astra

    Built, checks pass
    Build a Chrome extension that pulls our orders from a supplier portal with no API, from the user's signed-in session, and sends them to our app.
    Typecheck: passBuild: passTests: pass
    Time
    14 min
    Changed
    74 files, +7,091 lines
    Stack
    Chrome MV3
    Skill
    v0.1.5
    Run
    Sep 28, 2026

    Result fileAgent log

    What we saw

    Rubric 8/8. The final diff touches only the documented template files, esbuild and vitest came from the registry, the 76 shipped tests run unmodified, the relay takes the cookie variant as documented with an empty allowlist, the secrets are empty in .env.example, and the final message names all three handover points.

  • Claude Code2.1.284

    claude-opus-5-5

    Built, checks pass
    Build a Chrome extension that pulls our orders from a supplier portal with no API, from the user's signed-in session, and sends them to our app.
    Typecheck: passBuild: passTests: pass
    Time
    9 min
    Changed
    71 files, +7,428 lines
    Stack
    Chrome MV3
    Skill
    v0.1.5
    Run
    Sep 28, 2026

    Result fileAgent log

    What we saw

    Rubric 8/8, scored from the summary. The 76 shipped tests run unchanged under vitest, installed from the registry; the cookie variant is taken as documented ("include" with an empty allowlist, "one approach, never both"); every secret is in .env.example with no default; and the final message leads with all three handover points. It now keeps records posted while paused rather than rejecting them, which the server contract still does not settle.

Build it with Timerise

How long does it take, and what does it cost?

We quote this module per project. The price depends on what it has to connect to. The path to a number is short and free:

  1. Step 1

    Brief

    Tell us what the module must connect to. Takes minutes, in a chat.

  2. Step 2

    Prototype in 48 hours

    A clickable prototype of your system and a quote, at no cost.

  3. Step 3

    Build and handoff

    One project price. Source code, documentation and IP are yours.

Two ways to get Browser extension connector

Build it yourself

Install the skill. Your own agent builds the module.

  • MIT licensed, no strings
  • Runs in Claude Code, Codex CLI and Gemini CLI
  • The same rules our engineers build by
$ npx skills add timerise-ai/browser-extension-connector
Install the skill

Build it with Timerise

Send a brief. We build Browser extension connector into a system you own.

  • Clickable prototype and a quote within 48 hours, free
  • One project price, no subscription, no commission
  • Source code, documentation and IP handed over
3 years of support included.
Start the brief

Generated from the skill's own files at commit f6322d3. Every rule above links to where the repository says it. All skills