Let your AI agent drive your real browser. Your tabs, your cookies, your logins.
Most browser automation tools spin up a fresh, empty Chromium. That's great for tests, and pretty useless when you want an agent to check your orders, poke around an admin dashboard, or reproduce a bug you're logged in to see. Vitamine goes the other way: a tiny Chrome extension plus a local Bun server that exposes your actual browser to Claude (or any MCP client).
Claude ──HTTP MCP──> bun server (127.0.0.1:9333) ──WebSocket──> extension ──chrome.debugger──> your tabs
- Your real session. No separate profile, no re-logging in, no cookie juggling.
- Scripts, not clicks. Instead of one tool call per click, the agent sends a short async JS script that finds, clicks, waits, reads and loops in one go. Fewer round trips, fewer tokens.
- Human-style targeting. Point at things the way you would describe them:
page.click('Save'),page.fill('Email', 'a@b.c'),{ role: 'button', text: 'Download', near: 'Invoice #123' }. - Stays out of your way. Agent tabs open in the background, grouped under a "Vitamine" tab group, so you can keep working.
- Network, console and cookies built in. Inspect, replay and fetch requests with the page's own auth.
- Reusable scripts. Flows worth repeating get saved to
scripts/and run by name.
Requires Bun and a Chromium-based browser (Chrome, Vivaldi, Brave, Edge, Arc...).
git clone https://github.com/nitlix-studios/Vitamine
cd Vitamine
bun install
bun run build # compiles extension/src into extension/dist
bun run start # or `bun run dev` to reload on change- Open
chrome://extensions(orvivaldi://extensions, etc.) and turn on Developer mode. - Click Load unpacked and pick the
extension/folder. - On the extension's Details page, turn on Allow User Scripts. Fallback mode needs it (more on that below).
- The toolbar badge says ON once it's connected to the server.
For Claude Code:
claude mcp add --transport http --scope user vitamine http://127.0.0.1:9333/mcpAny other MCP client works too, just point it at http://127.0.0.1:9333/mcp over HTTP.
Quick sanity check:
curl localhost:9333/healthOnce it's connected, just ask your agent to do things in your browser. Under the hood it calls run with scripts like this:
const p = await tabs.open('https://example.com/login'); // background tab
await p.fill('Email', 'a@b.c'); // field labelled or next to "Email"
await p.click({ role: 'button', text: 'Continue' }); // waits for the page to settle
return p.snapshot();Or something a bit meatier, like scraping results after an autocomplete:
await page.pick('From', 'Nice', /NCE/);
await page.click('Search');
await page.waitFor(/results? found/i);
return (await page.readAll({ selector: '.result-card' }, { limit: 10 })).map(r => r.text);The MCP server exposes four tools:
| Tool | What it does |
|---|---|
tabs |
Lists every tab in every window. * marks the active one. |
run |
Runs an async JS script against a tab (the active one by default). |
scripts_list |
Lists saved scripts. |
scripts_save |
Saves a reusable script to scripts/<name>.js. |
Inside run, scripts get these globals: page, tabs, net, cookies, logs, scripts, sleep, log and args.
page.goto(url) // also reload(), back(), forward()
page.info() // url, title, viewport, scroll
page.snapshot() // one line per visible control: 'e12 button "Save"'
page.snapshot({ diff: true }) // only what changed since the last snapshot
page.snapshot({ grep: /price/i }) // search controls across the whole page
page.read({ around: '£36' }) // text around each match, not the whole page
page.readAll({ selector: '.card' }, { where: /9\./ }) // text of every match, filtered
page.dismiss() // closes cookie banners, prefers "Reject"
page.click(spec) // waits for the DOM and navigation to settle
page.fill(spec, text) // clears and types
page.pick(field, text, option) // autocomplete: type, then click the suggestion
page.type(text) / page.press('Enter') // also select(), check(), hover(), scroll()
page.waitFor(spec) / page.waitForUrl(/checkout/)
page.eval(fn, ...args) // run a function in the page
page.screenshot({ full: true }) // works on background tabs too
page.fetch(url, init) // sent with the page's cookiesActions wait up to 5s for their target and refuse to click covered elements. When nothing matches, the error lists the closest candidates so the agent can correct itself.
A spec is how you point at an element:
'Save' // substring of the name (aria-label, label, placeholder, text)
/Total: \d+/ // a RegExp
{ role: 'button', text: 'Download', near: 'Invoice #123' }
{ text: 'Search', within: { selector: 'form' } }
{ text: 'Delete', nth: 2 }
ref('e12') // a ref from a snapshottabs.list() / tabs.open(url) / tabs.get(id) / tabs.close(id)
net.capture({ reload: true }) // catch page-load requests too
net.list({ url: /api/, status: 500 })
net.body(id) / net.replay(id, { body })
cookies.get({ domain: 'example.com' }) // HttpOnly included
logs.list({ level: 'error' })The full API reference lives in the run tool description in server/tools.ts, which is exactly what the agent sees.
Anything you do more than twice can become a script. Ask the agent to save one, or drop a file into scripts/:
// Headings and links of the current page. args: {limit?: number}
const limit = args.limit ?? 10;
const headings = (await page.findAll({ role: 'heading' }, { limit })).map(h => h.name);
return { url: (await page.info()).url, headings };The first comment line becomes the description. Run it with run({ script: 'page-outline', args: { limit: 5 } }) or scripts.run('page-outline') from another script.
Vitamine has access to your real logged-in browser, so it's worth knowing what it does and doesn't do:
- The server only listens on
127.0.0.1and rejects requests with any otherHostheader, which blocks DNS rebinding. - The extension socket only accepts connections from
chrome-extension://origins. - Auth headers and cookie values are redacted in output unless a script explicitly asks with
reveal: true. - Other extensions' network traffic and console logs are hidden by default.
- The agent is told that page content is data, not instructions, and to confirm with you before sending, buying, posting or deleting anything. Still, keep an eye on what it's doing.
Chrome refuses to attach the debugger to pages where another extension (say, a password manager's inline menu) has a frame. When that happens, the tab switches to page.mode = 'dom' automatically and retries the debugger after 60 seconds. In fallback mode:
- Code runs in the page through
chrome.userScripts, and input is synthetic (isTrusted: false). - Navigation goes through
chrome.tabs. - Screenshots only work on the tab currently showing in its window, and there are no full-page shots.
- No network or console capture.
- Cookies come from
chrome.cookieseither way, so they work in both modes.
- Network and console capture start when Vitamine first touches a tab. Use
net.capture({ reload: true })to catch page-load requests. - Chrome shows a "started debugging this browser" bar while tabs are attached. Closing that bar detaches them.
- Only one extension can debug a tab at a time, so Claude in Chrome and Vitamine will fight over the same tab.
- v0.1 limits: main frame only (no iframes yet), and text search doesn't look inside shadow DOM.
bun run dev # server with reload on change
bun run watch # rebuild the extension on change
bun run typecheck # server and extensionAfter rebuilding the extension, reload it without touching chrome://extensions:
curl -X POST localhost:9333/reload-extensionSet VITAMINE_PORT to run the server on something other than 9333 (you'll need to update the extension's socket URL to match).
Apache-2.0. See LICENSE.