convez.ai
MCP ServerAutomaçãoIntermediário
jturle

Monica — Supervisor de Agentes em Navegador

jturle/monica

Painel de controle unificado para agentes navegadores — veja tudo ao vivo, assuma quando necessário

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que oferece supervisão em tempo real de múltiplas sessões de navegador controladas por agentes IA. Funciona como um painel de controle centralizado onde você observa todas as abas/panes simultaneamente, pode assumir o controle quando necessário (CAPTCHAs, logins) e cada pane é um alvo CDP anexável para automação remota via Puppeteer ou Playwright.

Instalação

$npx convez-ai jturle/monica

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Supervisionar múltiplos agentes web em paralelo com interface visual unificada
  • Intervir manualmente em tarefas que exigem CAPTCHA, autenticação ou decisão humana
  • Debugar e monitorar comportamento de agentes de automação em tempo real
  • Gerenciar sessões isoladas com persistência de dados (cookies, localStorage, IndexedDB)

Veredito

Ferramenta sólida para quem trabalha com agentes web em escala. Resolve um problema real — supervisão visual centralizada — sem overhead de complexidade. Recomendado para pipelines de automação que exigem intervenção humana ocasional ou debugging intensivo.

README

A tradução para o português deste README ainda está na fila.

monica

Keep tabs on your agents' browsing — and assist when required. Point them at monica (agent-browser or agent-browser-mcp, Puppeteer, Playwright — anything that talks CDP) and every session becomes a live pane, tiled like a security-camera wall or flipped to tabs. Watch the fleet in real time, and grab the wheel whenever one needs a human: a captcha, a login, or a quiet word about its life choices.

Every pane is a real, attachable CDP target, so a remote puppeteer.connect(...) + browser.newPage() just works — no spawning headless Chrome from a shell, juggling --remote-debugging-port, or forwarding ports. monica is the launcher, supervisor, and one-way mirror in one.

Quick start

Requires Node. Use whichever package manager you like — npm, yarn, and pnpm all work.

git clone https://github.com/jturle/monica
cd monica

npm install        # or: yarn   ·   pnpm install
npm start          # or: yarn start   ·   pnpm start

If Electron's binary wasn't fetched during install (some Yarn setups skip lifecycle scripts), run it once with node node_modules/electron/install.js, then start again.

monica opens to a welcome screen showing its CDP endpoint (http://127.0.0.1:9222). Point an agent at it — the welcome screen has a copy-paste agent-browser-mcp config — and the pages it opens appear as panes. Press ⌘G to switch between grid and tabs.

Prefer a real app? yarn install:app builds a local, branded monica.app and drops it in /Applications (macOS, unsigned — no release/notarization). yarn package just builds it under dist/.

Sanity-check that panes are CDP-attachable:

curl http://localhost:9222/json | jq '.[] | {title, type, url}'

Features

  • One wall of panes, two layouts. A flat set of browser panes shown either as tabs (one at a time) or an auto-tiled grid (⌘G). The grid's shape follows the pane count and the window aspect ratio (1×1, 2×1, 2×2, 3×2, 3×3 …, transposed when portrait), recomputed on resize. The layout choice is remembered.
  • Drive by hand or by agent. Click a pane to select it and use the omnibox, or attach over CDP — both at once is fine. Take over a pane your agent is driving at any time.
  • One CDP endpoint, live-rebindable. A Local (127.0.0.1) ↔ LAN (0.0.0.0) toggle rebinds the endpoint without a restart and is remembered; click the badge to copy the URL.
  • Named, isolated sessions. A client that connects with ?session=<name> gets its own scoped set of panes — sessions never see or trample each other's pages. A named session's panes share a persistent storage partition keyed by the session name, so cookies, localStorage, and IndexedDB survive reconnects and monica restarts (handy for staying logged in across runs). Anonymous and ⌘T user panes get a per-pane partition that resets each launch. The settings popover lists known sessions with Clear (wipe data, keep the name) and Forget (wipe + drop) — and agents can self-clear via standard CDP (Storage.clearDataForOrigin, Network.clearBrowserCookies).
  • Close means close; disconnect means detach. Closing a page (Target.closeTarget) removes its pane. When a named session's connection drops, monica discards that session's panes. An anonymous disconnect (e.g. puppeteer.disconnect()) leaves the panes running, matching real Chrome, so you can keep driving them by hand.
  • Welcome screen with copy-paste setup. Empty monica shows the live endpoint and a ready-to-paste agent-browser-mcp config plus agent prompts.

Connect an agent

monica exposes a CDP endpoint at http://127.0.0.1:9222 (or http://<lan-ip>:9222 in LAN mode — the badge shows the current address).

agent-browser-mcp (recommended)

The jturle fork of agent-browser-mcp (an MCP server wrapping the agent-browser CLI) drives monica over CDP and tags each agent session, so every session gets its own pane(s) and closing a session clears them. Add it to your MCP client (e.g. Claude Code's .mcp.json):

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["-y", "github:jturle/agent-browser-mcp"],
      "env": { "AGENT_BROWSER_CDP": "http://127.0.0.1:9222" }
    }
  }
}

AGENT_BROWSER_CDP is what points the MCP at monica — set it to the address monica shows (the LAN address when monica is in LAN mode or running on another machine). If your environment blocks npx's git fetch, clone the repo and run the build directly instead: "command": "node", "args": ["/path/to/agent-browser-mcp/dist/index.js"].

Puppeteer / raw CDP

A plain CDP client works without monica-specific code:

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserURL: "http://127.0.0.1:9222",
  defaultViewport: null, // monica sizes panes itself
});

const page = await browser.newPage();        // creates a pane
await page.goto("https://example.org/");      // watch it load in the grid
// ...drive it...
await browser.disconnect();                    // detaches; the pane stays (don't use close())

Attach to a pane that already exists (e.g. one you opened by hand) — they're webview-type targets, so enumerate and pick:

const browser = await puppeteer.connect({
  browserURL: "http://127.0.0.1:9222",
  targetFilter: (t) => t.type !== "browser", // required to see webview panes
});
const target = browser.targets().find((t) => t.type() === "webview");
const page = await target.page();

Good to know:

  • newPage() works, even though monica is an Electron host — the proxy turns Target.createTarget into a real pane (plain Electron would hang).
  • Panes render at their on-screen size. monica swallows client viewport emulation so content fills the pane and reflows as you tile/resize it.
  • No tunnel needed cross-machine: flip to LAN mode and connect to http://<lan-ip>:9222. (An SSH tunnel still works and adds auth/encryption.)

Architecture

  • Shell: Electron. Panes are <webview> elements positioned absolutely in the DOM, so grid/tabs layout, selection, and z-order are plain CSS/HTML; a webview is never reparented when the layout changes.
  • CDP proxy: real Chromium DevTools runs internal-only on 127.0.0.1:9223; monica's proxy owns the public :9222. It's a transparent WebSocket relay except it:
    • turns Target.createTarget into a new pane and Target.closeTarget into a pane removal,
    • swallows viewport-emulation calls,
    • scopes target discovery per ?session= (so sessions are isolated) and hides monica's own shell target from clients,
    • on a named session's disconnect, closes that session's panes (anonymous disconnects are left running).
  • Isolation: named-session panes share persist:session-<name> so storage carries across reconnects; anonymous and ⌘T user panes use persist:pane-<id> (id is per-launch, so de-facto ephemeral). Either way, cookies/storage/cache are scoped to that partition.
  • Settings: the Local/LAN bind and the grid/tabs layout are saved in monica-settings.json and restored on launch.

Keyboard shortcuts

ShortcutAction
⌘TNew tab (blank pane)
⌘GToggle grid / tabs
⌘← / ⌘→Back / forward in the selected pane
⌘RReload the selected pane
⌘WClose the selected pane (offers to quit when none are left)
⌘⇧RReload the monica app

Limitations

  • Incognito contexts (createBrowserContext) aren't supported — Electron doesn't implement them. newPage() on the default context is what's enabled.
  • LAN mode + allow-all origins means anyone on your network can drive your browsers. Use it only on a trusted network (a shared-secret token is a planned follow-up).

License

Apache License 2.0 — see LICENSE and NOTICE.

Ver o original no GitHub

Bom para

Relacionados