Shim

Change any website. Describe what you want ("hide the upsell banner", "add a notes field to every track", "put the columns I use first") and an agent writes a shim: a small, declarative patch that runs as a layer only you see. The site is never modified, and the original page is always one click away. When the site ships a new version, the shim re-finds what it changes on its own, with no AI involved, or holds the change for your review. It never silently attaches to the wrong element.

This repository holds Shim's open-source parts. The Shim browser is built on them.

Beta. Version 0.7.0 is the first public release. Nothing is on npm or the Chrome Web Store yet: everything installs from this repository's releases or from source. Expect rough edges, and please open an issue when you hit one.

What's here

Package	What it is
Shim for Chrome (@shimbrowser/extension)	Runs your shims in the Chrome you already use. Installs a .shim file, asks Chrome for access to exactly the sites it names, and keeps it applied as the site changes. Your coding agent can author on its tabs.
MCP server, Claude Code plugin and shim CLI (@shimbrowser/mcp)	The authoring loop for any MCP agent (Claude Code, Codex, …): the agent opens a session on a tab (in the Shim browser, Shim for Chrome, or a headless Chromium), edits the shim, previews it on the live page, checks a screenshot and iterates, then saves it. The shim command line packs, lints and previews shims, and sets up the Chrome bridge.
The engine (@shimbrowser/core)	What applies a shim to a page: anchors, the deterministic rebase, the spec format, and the contract every authoring host implements. No dependencies, no network, no AI.

Install

Each package's README has the full instructions, including what Shim for Chrome's permissions are for. In short, from the latest release:

Shim for Chrome. Download shim-for-chrome.zip and unzip it into a folder you will keep. Open chrome://extensions, turn on Developer mode, click Load unpacked and choose the folder. Then, on the extension's Details page, turn on Allow user scripts so shims with script handlers run. Full instructions.

The Claude Code plugin.

claude plugin marketplace add shimbrowser/shim
claude plugin install shim@shimbrowser

Without a GitHub SSH key, run export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 first. To author without the Shim browser or Shim for Chrome, also install Playwright's Chromium (npm install -g playwright && playwright install chromium). Full instructions.

The shim CLI and shim-mcp (also what connects your agent to Shim for Chrome):

npm install -g https://github.com/shimbrowser/shim/releases/latest/download/shimbrowser-mcp.tgz
shim --help

Codex and other MCP agents, after installing the CLI: codex mcp add shim -- shim-mcp, or { "mcpServers": { "shim": { "command": "shim-mcp" } } } in your client's config. The agent reads the authoring guide through the shim_guide tool. Full instructions.

The engine, as a dependency of your own project:

npm install https://github.com/shimbrowser/shim/releases/latest/download/shimbrowser-core.tgz

Every release file's SHA-256 is in the release's SHA256SUMS.

Build from source

Node 26 or later:

git clone https://github.com/shimbrowser/shim.git
cd shim
npm ci
npm run build        # every package: packages/*/dist
npm test             # every package's tests that need no browser

npm run test:browser also runs the tests that drive a real Chromium (Shim for Chrome loaded unpacked, the headless host, the CLI and the plugin end to end); run npx playwright install chromium once first. After a build:

• Shim for Chrome is unpacked in packages/extension/dist: load that folder.
• The Claude Code plugin runs from the checkout: claude --plugin-dir packages/mcp.
• The CLI is node packages/mcp/dist/shim.js (or npm link -w @shimbrowser/mcp for shim).

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first.

License

Apache-2.0. © Artificial Apps, LLC.