Ichiro

Ichiro lets a coding agent such as Claude Code or Codex read web pages and act on them in your own browser. It is a Chrome extension plus a small local MCP server that gives the agent one tool, browser.

The extension has no AI and needs no API key. Your agent decides what to do. Ichiro carries out each command, shows it in the side panel, and asks you before anything risky: paying, sending, signing in, or opening a site you haven't allowed.

Features

• The agent reads a page as a numbered list of things it can click or type into, then acts on those numbers.

• After each action the reply lists only what changed on the page, which keeps the agent's context small. Several commands can go in one call.

• Clicks and drags go through Chrome's DevTools Protocol, so pages see real mouse events. Pixel-based clicks and drags work on canvas apps like drawing tools and slide editors.

• pick lists every item built like one example, such as all the prices on a results page. repeat runs a finished item's steps on up to 30 more items after you approve the list once.

• PDFs are readable too, whether open in a tab or downloaded with your OK.

• Commands go to the agent's own tab, grouped under "Ichiro", so you can keep using another tab.

• Tips about a site ("the filters are under More") are saved by the agent and handed back on its next visit. You can delete any tip from the side panel.

• Always-on mode keeps the bridge running with the side panel closed and turns it back on when Chrome starts.

Related MCP server: webverb-mcp

How it works

coding agent ⇄ host/mcp.ts ⇄ local pipe + token ⇄ host/host.ts ⇄ extension ⇄ the page
   (stdio)       MCP server                         native host    background    content script
                                                                  + side panel

The agent starts host/mcp.ts as a stdio MCP server. Chrome starts host/host.ts through native messaging when the bridge is on. The two talk over a pipe with a random name, and every request must carry a token kept in a private file in your home folder. The extension runs each command in the agent's tab and sends back the result.

Safety

The agent drives your real browser, with your logins, so Ichiro puts you in the loop:

• Sites. The agent works freely only on sites you have allowed. A new site asks you first, and deep links to a new site are refused.

• Stop-lines. Actions that pay, book, send, check out or enter personal data pause and ask you.

• Hand-over. Sign-in, password and card fields, and CAPTCHAs are always left to you. Do the step yourself and press Resume.

• Downloads. Each download waits for your yes.

• Untrusted page text. Everything read from a page reaches the agent marked as untrusted, and the tool tells the agent never to follow instructions found there.

/auto on lets stop-lines, new sites, downloads and repeats go ahead without asking. It is off by default and isn't remembered. CAPTCHAs, password and card fields, and pause still wait for you.

Chrome warns about some permissions at install. debugger sends real mouse input, and Chrome shows its "debugging this browser" bar while a command runs. downloads lets Ichiro pause downloads until you allow them, and tabGroups makes the agent's tab group. Access to all sites is needed so the agent can read any page you allow.

Requirements

• Chrome 153 or newer. The installer also registers other Chromium browsers: Chromium, Edge, Brave and Vivaldi everywhere, plus Opera, Arc, Island and Prisma Access Browser on Windows.

• Node.js 22.18 or newer (the MCP server and native host are TypeScript files that Node runs directly).

• A coding agent that supports MCP over stdio.

Getting started

1. Clone this repository, then install and build:

   npm install
   npm run build

2. Open chrome://extensions, turn on Developer mode, click Load unpacked and choose .output/chrome-mv3/. Copy the extension ID shown on its card.

3. Register the native host. Run this once per computer, in your own terminal:

   npm run host:install -- <extension-id>

   On Windows, don't run it from inside a packaged app such as the Claude desktop app. Those apps hide registry writes from the browser, and the script refuses to run there.

4. Add the MCP server to your agent. For Claude Code:

   claude mcp add --transport stdio --scope user ichiro -- node /path/to/ichiro/host/mcp.ts

   Other agents: add a stdio server that runs node /path/to/ichiro/host/mcp.ts.

5. Click the Ichiro icon to open the side panel. A new install starts with the bridge on. Then ask your agent to do something in the browser.

Usage

Your agent sends lists of commands to the browser tool:

{ "commands": ["click 4", "type here \"hello\"", "key Enter"] }

It usually starts with help and read. Each reply begins with a step number, which repeat uses.

You control Ichiro from the side panel with slash commands:

• /mcp on and /mcp off turn the bridge on or off. /mcp on also adds the current site to your allowed sites.

• /sites lists allowed sites, and /tips lists saved tips. Both have Delete buttons.

• /always-on on|off keeps the bridge running with the panel closed.

• /auto on|off skips the asks described under Safety.

• /overlay on|off draws element numbers on every page the agent reads.

• /stop stops the agent's running command, and /help lists everything.

Troubleshooting

"The browser bridge is off." Open the side panel and type /mcp on.

The agent drives the wrong browser. With Ichiro in more than one browser, the agent drives the one that ran /mcp on last.

The bridge stopped working after you moved the folder. An unpacked extension's ID comes from its folder path, so loading it from a new place gives it a new ID. Run npm run host:install -- <new-id> again.

Development

npm run dev         # development build with reload
npm run build       # production build in .output/chrome-mv3/
npm run typecheck   # TypeScript check
npm test            # unit tests (Node's built-in test runner)
npm run host:uninstall

entrypoints/        the extension (WXT builds each entry)
  background/       runs commands and talks to the native host
  sidepanel/        the panel: log, asks, slash commands
  offscreen/        hidden page that reads PDFs
  content.ts        runs inside web pages
host/               MCP server, native host and installer (Node)
lib/                shared code, one folder per area
  bridge/           MCP bridge, message format, install paths
  page/             element list, page text, frames, diffs, screenshots
  actions/          clicks, typing, keys, real mouse input
  tabs/             navigation, waiting for pages, the agent's tab group
  safety/           stop-lines, personal data, CAPTCHAs
  memory/           site tips, panel settings, repeat
  files/            PDFs and downloads
  panel/            side panel port and readable log
docs/               design notes
tools/test-site/    local site for live checks
art/                logo sources

Each test sits next to the file it checks, such as lib/page/reader.test.ts. Ichiro is built with WXT, TypeScript and Preact. The panel's look follows docs/DESIGN.md.

Most testing so far has been on Windows with Chrome and Edge. Keyboard shortcuts on macOS haven't been checked on a real Mac yet.

Contributing

Issues and pull requests are welcome. Before you open a pull request, run npm run typecheck and npm test. Security guards (stop-lines, Sites, secret fields, the bridge token, untrusted page text) need tests in the same change that touches them.

License

Ichiro is released under the MIT License.