Browser Code: Teaching AI to Grow Userscripts

Original article (Japanese): Browser Code: AIにuserscriptを育てさせる仕組み

Have you ever thought, "I just want this one part to be a bit more usable" or "I want to change the display and behavior to match my workflow" when using existing websites?

Tools for "AI controlling browsers" already exist with Playwright and Puppeteer. But that's not what Browser Code is aiming for.

Not "AI controls it," but "AI grows persistent userscripts to continuously reshape sites to your specifications." That's the essence of Browser Code.

Browser automation (replaying operations) versus dynamic userscript generation (permanent modifications). Understanding this difference reveals where it works and where it doesn't.

What Browser Code Is (Not Browser Automation)

Browser Code operates as a browser extension, treating a page's DOM (Document Object Model) as a "virtual file system." It has Claude generate userscripts in JavaScript, then persists and auto-executes them via the chrome.userScripts API (a userscript persistence mechanism like Tampermonkey).

Virtual File System Structure

/{domain}/{url-path}/

├── page.html           # Live DOM (read/write)

├── console.log         # Console output (read-only)

├── screenshot.png      # Screenshot (on-demand)

├── plan.md             # AI's plan (for Plan/Execute mode)

├── scripts/

│   ├── my-script.js    # Saved userscript

│   └── _auto_edits.js  # Script generated from DOM edits

└── styles/

    └── custom.css      # Custom CSS

Difference from Browser Automation

In other words, Browser Code is a tool for "permanently changing a site's appearance and behavior," not "automating the same operations every time."

Persistence Mechanism (What Gets Saved)

Browser Code's "persistence" operates on two layers.

What persists: The userscript itself

• 
  ./scripts/*.js and ./styles/*.css are saved in extension storage (browser.storage.local)


• When saved, they're registered with chrome.userScripts.register() and auto-execute on the same URL (or pattern) thereafter


• Supports dynamic route matching (/products/[id], etc.) with parameters available via window.__routeParams
  

What doesn't persist: DOM state itself

• Reloading the page resets the DOM to its original state


• However, saved userscripts re-execute, so "the result is the same appearance/behavior is reproduced"

This design allows you to create a state where "once configured, that site always displays in your customized way."

Conditions for Suitable Use Cases

Working backward from Browser Code's design, it's particularly effective for sites meeting these conditions:

1. Sites Where Improvement Requests Don't Get Through

Why it's suitable: The official side has no reason to respond, development resources aren't allocated

Examples:

• Internal systems (Salesforce/kintone/Redmine admin panels)


• Business tools (ERP, workflow systems)


• Government sites (e-Gov, e-Tax)


• Academic DBs (J-STAGE, CiNii, PubMed)

These sites will never see UI improvements because "user count is small," "there's no budget," or "specification changes are difficult."

2. Overseas SaaS with Thin Japan Support

Why it's suitable: Sloppy localization, no Japan-specific features, support requests don't get through

Examples:

• Fixing Japanese display issues in Figma/Notion/Linear


• Adding Japan-specific displays to Stripe/Shopify admin (tax rates, invoice numbers)


• Defaulting GitHub/GitLab issue templates to Japanese

Overseas services often have "only Japan is inconvenient" spots, and it's sometimes faster to fix it yourself than wait for official support.

3. Personal Workflows

Why it's suitable: The official side has no reason to respond, specialized for personal workflows

Examples:

• Transcribing info from Site A to Site B's form (job listings → spreadsheet, papers → Notion)


• Consolidating info from multiple tabs into one view


• Monitoring for specific keyword appearances and notifying Slack/Discord

These "personal combinations" have no official integrations, so userscripts are the only way to fill the gap.

4. Sunset/Maintenance-Ended Services

Why it's suitable: Officials won't improve it, but you still want to use it

Examples:

• Maintaining old UIs for Google services (Calendar, Gmail)


• Automating data export from services with termination announcements


• Scraping alternatives after API deprecation

When maintaining features that officials have "abandoned," userscripts are a realistic option.

Unsuitable Use Cases (Limitations with Major Sites)

Conversely, conditions where Browser Code doesn't work well are also clear.

Major Sites Generally Meet User Demands

Major sites like Amazon, Rakuten, YouTube, and Twitter (X) have limited need for userscripts for these reasons:

• 
  Already officially supported: Features with high user demand are implemented officially


• 
  Frequent spec changes: Userscripts break whenever DOM structure changes


• 
  Abundant existing extensions: Ad blocking, dark mode, etc. have dedicated extensions

For example, "blocking YouTube ads" is handled by uBlock Origin. "Filtering Twitter timeline" is sufficient with official mute features.

Why I Don't Write Specific Changes

This article doesn't mention specific site names or change contents like "optimizing internal system input forms" or "strengthening government site validation." Two reasons:

1. 
   Site spec change risk: Writing specific DOM structures or class names becomes immediately outdated when sites update


2. 
   Lack of universality: Code for specific sites can't be reproduced in readers' environments

Instead, I presented decision criteria for "what kind of sites can use this."

Meaning of Plan/Execute Workflow

Browser Code adopts a two-stage "Plan/Execute" workflow to prevent AI runaway.

Plan Mode (Default)

• AI explores the page and writes change proposals in plan.md
  


• DOM changes and script writing are not allowed
  


• Users confirm the plan before switching to Execute mode

Execute Mode

• After user approval, AI executes the plan


• File writing, DOM editing, and script execution become possible

This design reduces the risk of "AI accidentally breaking the site."

Installation and Initial Setup (Chrome/Firefox)

Browser Code is currently used as a browser extension. Roughly speaking, "build it and load it as an extension."

Building

Building uses Bun.

bun install



# Development

bun run dev           # Chrome

bun run dev:firefox   # Firefox



# Production

bun run build         # Both browsers

Loading in Chrome

1. Open chrome://extensions
   


2. Enable Developer mode


3. Click Load unpacked and select .output/chrome-mv3/
   


4. Enable User scripts permission in extension Details (required for CSP bypass)

*Depending on Chrome version, it may lean toward the "Allow User Scripts" toggle side, so if it doesn't work, first suspect whether chrome.userScripts is enabled.

Loading in Firefox

1. Open about:debugging#/runtime/this-firefox
   


2. Click Load Temporary Add-on and select any file under .output/firefox-mv2/
   

Firefox lacks the File System Access API, so local sync assumes export (WebExtensions downloads API).

Before installation, it's reassuring to briefly check Releases, Commits, and Issues.

As of 2026-01-29, there are no Releases, and the last push was 2026-01-25 (UTC). Personally, I think it's safe to treat it as an "experimental tool" for now and track it with a fixed commit hash.

Technical Constraints and Workarounds

When using Browser Code, note the following constraints:

The CSP (Content Security Policy) Wall

Some sites (like LinkedIn) have strict CSP settings, and normal JavaScript injection won't work.

Workaround: Using Chrome 120+'s userScripts API can bypass CSP. However, you need to enable "User scripts" permission in extension settings.

Trusted Types Constraints

Some sites enable Trusted Types (a mechanism restricting dangerous strings from being injected into innerHTML, etc.), causing DOM operations to fail.

Workaround: Use DOM APIs like createElement and appendChild.

Firefox Sync Limitations

Firefox lacks the File System Access API, so bidirectional sync with local files isn't possible.

Workaround: Operate export-only (via Downloads API).

Summary: The Boundary Where Browser Code Works

Browser Code is a "dynamic userscript generation" tool, not "browser automation." It's suitable for sites meeting these conditions:

Conversely, for major sites, "already officially supported" and "existing extensions are sufficient" cases are common, limiting its applicability.

If interested, first think of "a site you use every day but is slightly inconvenient." That might be where Browser Code has a role.

Reference Links

• Browser Code - GitHub


• Browser Code - Commits


• Browser Code - Issues


• Browser Code - Releases


• Chrome userScripts API


• Chrome extensions - Match patterns


• Chrome Extensions Samples - userScripts


• File System Access API


• CSP (Content Security Policy) - MDN


• Trusted Types - web.dev


• DOM (Document Object Model) - MDN


• WebExtensions downloads API - MDN


• Tampermonkey


• Playwright


• Puppeteer


• Bun