Tabhand
Get Tabhand

Docs

Tabhand lets your AI agents use your own Chrome, in background tabs of their own. Here’s how to set it up, what your agents get, and what to do when something goes wrong.

Setup

You need macOS, Google Chrome and Node.js 20 or later.

npx tabhand setup

Setup does four things:

  • It installs Tabhand in ~/.tabhand and connects it to Chrome.
  • It adds Tabhand to every agent it finds, for all your projects. Each new session gets the browser tools, and the server’s instructions tell the agent when to use them.
  • It asks before changing anything. Where an agent has its own mcp add command, setup uses it. Otherwise it edits the agent’s settings file in place, keeping your comments, and backs up the original to ~/.tabhand/backups.
  • It walks you through adding the extension to Chrome, which you only do once.

Agent sessions that were already open pick up Tabhand after a restart.

Adding the extension

Tabhand’s Chrome Web Store listing is in review. Until it’s approved, you load the extension yourself. Setup copies the extension’s folder path to your clipboard and waits for Chrome:

  1. Open chrome://extensions and turn on Developer mode (top right).
  2. Click Load unpacked, press ⌘ ⇧ G and paste the folder path.

Once Chrome connects, setup says All set.

Updating

Run setup again with the latest version. It updates the extension too.

npx tabhand@latest setup

Agents

Setup adds Tabhand to each of these that it finds on your Mac:

  • Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Qwen Code
  • VS Code (Copilot), Copilot CLI, Kiro, Amp, Factory Droid, Warp, Junie, Antigravity
  • Devin Desktop, Windsurf, Claude Desktop, Cline, Zed

To add it to only some of them:

npx tabhand setup --harness claude,codex

Any other app that speaks MCP can start the server itself with ~/.tabhand/bin/tabhand mcp. Add --label and --theme to choose the name and colors on the agent’s cursor, for example tabhand mcp --label Researcher --theme agent.

Using it

Ask your agent in plain words, like “check that signup works on staging” or “find the March invoice in my email”. It opens a tab of its own in the background and gets to work.

  • Each agent session gets its own tab group, named after the agent, and its own cursor and tab icon.
  • An agent can only reach the tabs it opened, plus tabs and popups those pages open.
  • Agent tabs are muted, and Chrome never comes to the front.
  • Tabhand tells agents to ask you before sending messages, posting, buying, deleting or changing settings.
  • To pause every agent, click the Tabhand icon in Chrome’s toolbar, or Cancel on Chrome’s “started debugging” bar. Click the icon again to resume.

Tools

These are the tools your agent gets. Every one of them only works on the agent’s own tabs.

Tool What it does
browser_open_tab Open a background tab in the agent’s tab group, optionally loading a URL
browser_navigate Load a URL in one of the session’s tabs
browser_snapshot Read the page as an accessibility outline; things the agent can act on get refs like e123
browser_click Click an element by ref
browser_type Type into a field, optionally clearing it first and pressing Enter after
browser_press_key Press a key or a combination such as Shift+Tab
browser_scroll Scroll up or down
browser_upload_file Attach files from your computer to a file field, or through a button that opens a file picker. No dialog appears.
browser_screenshot Screenshot a tab, even in the background
browser_list_tabs List the session’s tabs
browser_close_tab Close one of the session’s tabs

Commands

Command What it does
npx tabhand setup Install Tabhand, add it to your agents and connect Chrome
npx tabhand status Check the install, the Chrome connection and each agent
npx tabhand remove Take Tabhand out of every agent and delete its files

Troubleshooting

Your agent says Chrome isn’t connected. Open Chrome and check that Tabhand is turned on at chrome://extensions. Then run npx tabhand status.

Your agent doesn’t have the browser tools. Restart the agent’s session. Sessions that were open before setup pick up Tabhand after a restart. npx tabhand status shows which agents have it.

Chrome never connects. The helper’s log says why. It’s at ~/Library/Application Support/tabhand/host.log, and it never contains URLs, page content or anything typed.

Chrome shows “Tabhand started debugging this browser”. That bar is how Chrome shows that an extension can control tabs. Tabhand only attaches to tabs its agents opened. Clicking Cancel pauses every agent.

Removing it

npx tabhand remove

This takes Tabhand out of every agent and deletes its files. Then remove the extension at chrome://extensions.

Contributing

Tabhand is open source under the MIT License. To work on it:

git clone https://github.com/tabhand/tabhand
cd tabhand
npm install
node bin/tabhand.mjs setup    # builds dist/tabhand.mjs and installs it from this checkout
node bin/tabhand.mjs reload   # after changing the extension's code

npm test runs the test suites. Issues and pull requests are welcome on GitHub.