---
name: buoy-web-install
description: Set up Buoy Web so an AI coding tool can use the web in Chrome, then tell the user the steps only they can do.
---

# Set up Buoy Web

Buoy Web lets an AI coding tool (Claude Code, Cursor, Codex, VS Code) use the web in Chrome with real clicks. It is free and needs no account. It is not tied to one app or repo: it is set up once, for every project, in each editor's user-level MCP config. Nothing goes in the current project.

The user-facing docs are https://buoy.gg/buoy/latest/docs/buoy-web.md (raw markdown).

## Rules that do not bend

The user's explicit instructions outrank this section.

- Do not edit, add or delete files in the current project. Do not commit.
- Do not read or print `.env*` files, keys, or credentials.
- Do not install Google Chrome, Node, or any other software. If something is missing, stop and tell the user.
- Do not open Chrome or try to add the extension yourself. The user does that.

## Before you start

1. Check the system with `uname -s`. Buoy Web for AI coding tools works on a Mac (`Darwin`) for now. On anything else, stop and tell the user: the coding-tool part is Mac only today, and Ask Buoy in Chrome (the extension's side panel) works on every system.
2. Check that `npx` runs. If it does not, stop and tell the user Buoy Web needs Node.js.
3. Check that Google Chrome is installed, for example `/Applications/Google Chrome.app`. If it is not, keep going, and tell the user at the end that Buoy Web needs Google Chrome.

## Set it up

Run this once:

```bash
npx -y @buoy-gg/mcp@latest init --web
```

It adds an MCP server named `buoy-web` to Claude Code (user scope), Cursor (`~/.cursor/mcp.json`), Codex and VS Code, for whichever of them are installed. For Claude Code, Cursor and Codex it replaces an older `buoy-web` entry if there is one. It also sets up a small Chrome helper so the extension can reach Buoy Web. It prints what it did and what it skipped.

Read its output. If it says Claude Code or Codex could not be set up, it prints the exact command to fix that editor. Run that command once. If it fails again, report it. It skips Codex and VS Code without a note when their command (`codex`, `code`) is missing, and prints nothing when the VS Code step fails. So if the user uses Codex or VS Code and the output has no line for it, check that editor's MCP list and report what you find.

Do not add `buoy-web` to the project's own MCP config (`.mcp.json`, `.cursor/mcp.json` in the repo, `.vscode/mcp.json`). The user-level entry already covers every project.

## Verify

Run `claude mcp list` (or the matching command for the editor you are in) and check that `buoy-web` is listed. Do not try to call Buoy Web's tools in this session: the editor only loads the new server after a restart.

## What only the user can do

Tell the user these steps, in this order:

1. Add the Buoy Web extension to Chrome from the Chrome Web Store: https://chromewebstore.google.com/detail/buoy-web/cfolfiajhlenfifknbomdogooagnlamf. Click Add to Chrome. Without the extension, Buoy Web still works: it opens its own Chrome window, and keeps its sign-ins in `~/.buoy/web-profile`.
2. Restart the editor.
3. Ask the AI to do something on the web, for example "Find the weather in Provo this weekend."

Also tell them:

- Buoy Web only works in tabs it opens. It never types into password fields, or into code and card fields the site marks; the user types those.
- Once a day it sends a small usage count: a random id, its version, the system type and a Buoy Web tag. No web addresses or page text. `BUOY_TELEMETRY=0` or `DO_NOT_TRACK=1` turns it off.

## Report the result

List what `init --web` set up and what it skipped, any errors in full, whether Chrome was found, and the user's remaining steps from above. Do not claim Buoy Web works until the user has restarted the editor and tried it.