Personae

Personae

A multi-identity browser · every identity is an isolated partition, every window is agent-controllable

Bundles agent-browser and an MCP server — no Node or CLI install needed

English · 中文

An Electron desktop browser that combines two things: multi-account isolation and letting AI agents drive the browser.

• Each browser identity is its own Chromium persist: partition — cookies, localStorage and login state are fully isolated, so you can be signed into the same site under several accounts at once.
• Each identity is a standalone window with back/forward buttons and an address bar. It behaves like an ordinary browser.
• The agent-browser binary is bundled, and those windows are exposed over MCP, so Codex / Claude Code can drive the page of a specific identity.

Users don't need to pre-install Node, Chrome for Testing, or any CLI.

MCP Registry

Personae is published to the official MCP Registry as io.github.leek-emperor/personae after its first Registry-enabled release. The Registry package is a small stdio launcher for a running, separately installed Personae desktop app — it does not replace the browser application or create a cloud browser.

After installing and launching Personae, a client that supports npm MCP packages can run:

npx -y @leek-emperor/personae-mcp

The launcher discovers Personae through its local bridge and keeps each tool call scoped to the identity named in the request. It uses no API key and opens no public network listener. The app's Configure Codex control remains the recommended setup path because it uses the bundled Electron runtime and needs no Node installation.

The problem it solves

Existing browser-automation tools assume the agent launches the browser. If your product _is_ a browser client, it's the other way around: the windows already exist, and they belong to different account identities. What the agent needs is to attach without crossing identities.

The approach here:

1. The app opens a CDP port on startup (system-assigned, loopback only).
2. When an identity window opens, the main process resolves the authoritative targetId of its content page via Target.getTargetInfo.
3. A local bridge exposes the identity → targetId mapping.
4. The MCP server uses that targetId directly as a tab ref — a single-step hit.

So snapshot(identity: "Account A") and snapshot(identity: "Account B") always land on the right window, even when both have the same site open with identical titles and URLs.

Quick start

Requires Node ≥ 20 and pnpm (for development only; the packaged app depends on neither).

agent-browser must be ≥ 0.36. Below that, tab list --json does not emit targetId, which is the only thing tying an identity to its window — every tool would fail to find its target. The version in package.json is already pinned; don't downgrade it.

pnpm install

pnpm bundle:ab # copy the agent-browser binary and core skill into resources/ pnpm dev

Add one or two browser identities in the UI, then click an identity to open its window.

The interface is in English by default. Use the EN / 中 toggle in the top-right corner to switch to Chinese; the choice is remembered and also applies to the toolbar inside each identity window and to the agent prompt you copy out.

Tests

The tricky, mostly-undocumented decisions live in small pure modules so they can be locked down by tests. They run on node:test with no extra dependencies:

pnpm test

Covered: the window.open / popup decision (window-open.ts), the proxy input parsing (proxy.ts), address-bar URL normalization (url-input.ts), the Codex-config TOML splice (toml.ts), and the identity palette (colors.ts).

Packaging:

pnpm build:mac      # or build:win

The default is adhoc signing (identity: '-'), which needs no Apple Developer certificate and runs fine on the build machine. But an adhoc-signed app cannot be distributed — Gatekeeper will block it on someone else's Mac. For real distribution, supply a certificate via environment variables and set notarize to true:

CSC_LINK=/path/to/cert.p12 CSC_KEY_PASSWORD=... \

APPLE_ID=... APPLE_APP_SPECIFIC_PASSWORD=... APPLE_TEAM_ID=... \ pnpm build:mac

Connecting Codex / Claude Code

The fastest path: let the agent connect itself

The UI has a "Let the agent connect itself" block that renders a ready-to-send prompt. Copy it, paste it into Codex or Claude Code, and the agent will write its own MCP config, restart, and verify the link by calling list_identities.

The prompt isn't just a config snippet — it also tells the agent what the 13 tools do and which mistakes to avoid (stale refs, guessing at agent-browser syntax, trying to tell identities apart by page title). It's generated from live runtime values, so the paths in it are always correct for the machine it's running on.

Or click one button

The same panel has a one-click install that writes the MCP server into ~/.codex/config.toml (idempotent, with an automatic backup first). Paths are resolved at runtime from process.execPath, so they can't be wrong.

Or configure it by hand

On macOS:

[mcp_servers.personae]

command = "/Applications/Personae.app/Contents/MacOS/Personae" args = ["/Applications/Personae.app/Contents/Resources/mcp-server.mjs"]

[mcp_servers.personae.env] ELECTRON_RUN_AS_NODE = "1"

The executable under Contents/MacOS/ follows productName, so it's Personae. Note that electron-builder's executableName only applies to Windows.

command points at the app's own binary; ELECTRON_RUN_AS_NODE=1 makes it degrade into a plain Node runtime. That's why no Node install is required (verified: with PATH set to /usr/bin:/bin, the full flow still works).

Claude Code:

claude mcp add personae \

--env ELECTRON_RUN_AS_NODE=1 \ -- /Applications/Personae.app/Contents/MacOS/Personae \ /Applications/Personae.app/Contents/Resources/mcp-server.mjs

MCP tools

Every tool takes an identity argument (name or id).

When click / fill receive an @eN ref they automatically take a snapshot first, because refs are only valid within a single agent-browser process — reusing one across processes always fails with Unknown ref. For multi-step interactions, put them in one act batch.

Driving a popup child window. When a page opens a popup (an OAuth sign-in, a share dialog…), that popup becomes a child window belonging to the same identity (see Popups and OAuth). It's a separate CDP target, listed under the identity in list_identities as children. Every acting/reading tool takes an optional target argument — pass a child's targetId (or its index) to drive the popup instead of the main window; omit it to drive the main window as before.

Architecture

┌─────────────────────────────────────────────────────────┐

│ Electron main process │ │ │ │ ├─ CDP server (port 0 → system-assigned, 127.0.0.1 only)│ │ ├─ IdentityManager storage / window lifecycle / target │ │ └─ Agent Bridge local HTTP, exposes identity↔target │ └───────────┬─────────────────────────────────┬────────────┘ │ │ ┌─────────▼──────────┐ ┌───────────▼───────────┐ │ Identity window │ │ Discovery file │ │ (one per identity) │ │ userData/ │ │ │ │ agent-bridge.json │ │ BrowserWindow shell│ │ (port changes every │ │ ├ WebContentsView │ │ launch; found via │ │ │ chrome.html │ │ a fixed path) │ │ └ WebContentsView │ └───────────┬───────────┘ │ content │ │ │ ↑ agent acts │ │ └────────────────────┘ │ │ ┌─────────────────────────────────▼───────────┐ │ scripts/mcp-server.mjs (stdio JSON-RPC) │ │ read discovery → get targetId → run CLI │ └───────────────────┬─────────────────────────┘ │ ┌───────────▼────────────┐ │ Codex / Claude Code │ └────────────────────────┘

Why each identity window is "a shell plus two WebContentsViews"

The goal is to wrap third-party pages in our own navigation UI without using the tag. So:

• the shell BrowserWindow is only a container and loads about:blank;
• the top bar is a local chrome.html with a dedicated preload exposing just six navigation methods;
• the content area is a WebContentsView where the partition applies, and it deliberately loads no preload at all, keeping third-party pages untouched.

Nested BrowserWindows and BrowserView both work too, and the agent can drive all three (all verified). WebContentsView was chosen because BrowserView is marked @deprecated in Electron's type definitions, and because a nested window is a separate native window on macOS — dragging, resizing and minimizing would