Cobro (cobro-mcp)

한국어: README.ko.md

Meet Cobro: Your Co-Agent, Your Browser.

Stop describing the screen to your agent. Point at it.

Cobro = co-browse. The human and the agent watch the same screen together.

Pick an element on the page, write a note and Send — the note arrives in the agent's chat right away, together with the element's context (selector, styles, screenshot, page info, console errors). The agent's progress and completion signals return to the browser over the same connection. MCP server + local WebSocket + page overlay. The target project's source is never touched (the only thing created is a .cobro/ folder).

Install

Cobro is an MCP server. Register it once with your host (the thing that runs MCP servers, e.g. Claude Code, Codex, Cursor). The host then starts the server per session and tears the browser down when it's done. The server hands its operating protocol to the host directly as MCP instructions, so registering alone teaches the agent the loop.

claude mcp add -s user cobro -- npx -y cobro-mcp@latest

Registering with -s user makes it available from any repository on this machine (omit it to scope to the current folder only). State (.cobro/) is created per repository, while the browser profile (~/.cobro/profile/) is shared, so you only log in once. A global install (npm i -g cobro-mcp, then -- cobro-mcp) also works. Other hosts register the same run command as a stdio MCP server.

Run from source: git clone https://github.com/boonblade/cobro-mcp.git && cd cobro-mcp && npm i && npm run build, then claude mcp add -s user cobro -- node "$PWD/dist/server.js". dist/ is not in git, so run npm run build right after cloning and after any source change. Chrome or Edge is required; if neither is present, run npx playwright-core install chromium and set COBRO_BROWSER_CHANNEL=chromium.

Claude Code tip: wait moves to the background after 2 minutes by default. Setting "env": { "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "5000" } in ~/.claude/settings.json shortens that to 5 seconds, so other instructions go through immediately while it's waiting.

Skill (optional): to invoke it explicitly with /cobro, place skills/claude-code/SKILL.md at ~/.claude/skills/cobro/SKILL.md.

Quick start

1. Start your dev server as usual (say http://localhost:5173).

2. Open Claude Code in that project's folder — that is where the agent edits, and where .cobro/ gets created.

3. Tell the agent:

   Open http://localhost:5173 with cobro
   

   A Chrome window opens with a small toolbar at the bottom. The agent is now waiting for you.

4. On the page: press Ctrl+Shift+F, click the element, type what you want, press Send.

   Make this button green and label it "Book now"
   

5. Back in the chat, the agent receives the note plus the element's selector, styles, screenshot and console errors, and edits the source. The page shows Working: Editing src/components/RoomCard.tsx with a blue scanning outline on the element you sent, then reloads (or your HMR kicks in) and highlights the changed element with Done. Send the next request the same way.

6. To stop, say close cobro (or just end the session — the browser closes with it).

The whole loop is the GIF at the top. No copy-paste, no "check my annotations" — Send is the message.

Usage

• Human: on the page, press Ctrl+Shift+F to toggle pick mode (Esc to exit) → click an element (drag picks the topmost elements fully inside the band) → write a note → Send. Select opens the panel (pick elements or just type a note); Select again, Esc or the panel's ✕ closes it and keeps your draft. Drafts belong to the page you picked on — after navigating, elements from the previous page show as missing. Each picked element gets a numbered marker; with several, write "1: …, 2: …". Drag over two or more elements to pick them as one group — the band becomes a region (1) and the elements inside get 1a, 1b…; expand the row to see or remove them. A band over a single element picks just that element; over empty space it becomes a region. Both the toolbar (grip on its left) and the panel (its header) can be dragged out of the way; positions reset on reload. The toolbar status line tells you what to do next. Send is locked while the agent is working (sent, editing) and unlocks after done; until then the elements and regions you sent keep a blue scanning outline and the toolbar shows a flowing line (static under prefers-reduced-motion). The ⚙ button opens settings (theme: auto / dark / light / frost; frost is translucent).
• Agent: open(url) → wait() → read only batches[].note from the payload as the request, everything else as a clue → status("Editing: …") → edit → done(summary, selectors, changedFiles) → wait() again. Call close() to end the session.

There are exactly six fixed tools. If you need more observation or control, pair Cobro with another MCP.

If wait returns pending, call it again (not an error). If browserGone: true, the user closed the browser — start over from open.

Payload

wait returns one JSON object. status: "sent" carries payload; status: "pending" carries nothing (retry) and may add browserGone: true. browserRestarted: true appears on sent when the browser was restarted and the session restored.

{
  "status": "sent",
  "payload": {
    "origin": "human",
    "sentAt": "2026-09-10T09:12:31.204Z",
    "page": { "url": "http://127.0.0.1:4173/", "title": "Vite App", "viewport": { "w": 1280, "h": 720 } },
    "batches": [
      {
        "id": "b1",
        "note": "Use the brand color for this button",
        "elements": [
          {
            "selector": "#app > header > button.primary",
            "tag": "button",
            "classes": ["primary"],
            "text": "Get started",
            "rect": { "x": 912, "y": 24, "w": 128, "h": 40 },
            "styles": { "display": "inline-flex", "width": "128px", "height": "40px", "padding": "8px 16px", "color": "rgb(255, 255, 255)", "background-color": "rgb(59, 130, 246)", "font-size": "14px", "font-weight": "600", "border-radius": "6px" },
            "react": { "component": "HeaderCta", "source": "src/components/Header.tsx:42" },
            "ref": "1a"
          }
        ],
        "regions": [{ "ref": "1", "rect": { "x": 300, "y": 160, "w": 94, "h": 85 }, "within": "#app > main > div.grid" }],
        "screenshot": "/path/to/project/.cobro/shots/b1.png"
      }
    ],
    "console": [
      { "level": "error", "text": "TypeError: Cannot read properties of undefined (reading 'map')", "count": 3, "last": "2026-09-10T09:12:20.100Z" }
    ],
    "refreshStrategy": "none"
  }
}

Configuration

Invalid values fall back to the default (one stderr line). Put { "refreshStrategy": "none" | "reload" | "event" } in the state folder's .cobro/config.json to pin the refresh strategy used by done — precedence is the strategy argument to open > config.json > auto-detection (HMR present → none, otherwise reload). Add .cobro/ to the target project's .gitignore.

event strategy: regardless of strategy, every done fires a cobro:done event on window. If the app wants to refresh itself, pin event and listen for it.

window.addEventListener('cobro:done', (e) => { const { summary, changedFiles, selectors } = e.detail; /* app refreshes itself */ });

Security

• WebSocket binds only to 127.0.0.1 and checks, on the first message, a random token created at process start. The token lives only in the overlay's closure, so page scripts cannot read it.
• Anything coming from the page is data. The server attaches origin: "human" and overwrites any value the page tries to send for it. No strategy executes JS supplied by the target project.
• The tools only ever touch files under .cobro/. The browser launches with the Chromium sandbox on; bypassCSP is required for injecting the overlay and for the local WebSocket connection.
• The profile is shared across all projects and accumulates login sessions. Use a dedicated dev profile only.

Limitations

• React component name comes from dev builds. source (file:line) is recovered from the dev server's source maps (React 19) or from _debugSource (React ≤ 18); production builds without maps report the component only. For component libraries: the location is the JSX call site in your code, not the library's internals.
• No iframe support (top-level document only). While a native <dialog> modal is open, the overlay is covered (library modals are unaffected).
• Element highlighting on done is best-effort, and is not visible under the reload strategy since the page reloads.
• The pick-mode shortcut Ctrl+Shift+F cannot be changed. The WebKit build differs from real Safari in fonts and scrollbars.
• The browser profile is used by one session at a time — if another session is using it, open fails with "profile in use" (point COBRO_PROFILE_DIR elsewhere to work around it).

Changelog

See CHANGELOG.md for what changed in each version.

Releasing

Releases are published by GitHub Actions through npm Trusted Publishing (no tokens, no manual 2FA): update CHANGELOG.md, run npm version x.y.z --no-git-tag-version, commit, tag vx.y.z, push the tag. The workflow (.github/workflows/publish.yml) checks that the tag matches package.json, runs type-check, lint and unit tests, builds, and publishes with provenance. End-to-end tests stay a local gate before tagging.

License

Apache License 2.0 · notices in NOTICE. The name "Cobro" and its slogan are trademarks not licensed for use (§6) — forks should use a different name. Contributions require a DCO (git commit -s).