Your agents (Claude Code, Codex, Cursor or your own) run browser tasks in their
own task spaces inside one shared Chromium, signed in with your real logins,
while your own tabs stay yours. Instead of a navigate → look → click → look
round trip per step, the agent writes one JavaScript block that does the
whole task, so runs finish faster on fewer tokens.
- Stock Chromium, no custom build. It drives the Chrome, Chromium, Brave or Edge you already have, over the Chrome DevTools Protocol.
- Your logins carry over. Import your Chrome profile once, and agents land on pages already signed in.
- Parallel, owned task spaces. Each task gets its own tabs and an owner, so agents don't collide, and you can take over halfway through.
- CLI or MCP. A heredoc CLI for agents with a shell, and a one-tool MCP server for everyone else.
Renamed from
opencue/ego-lite-linux. GitHub redirects the old URLs; update your remote when convenient:git remote set-url origin https://github.com/opencue/agenticbrowser.git. On-disk names (profile directory,.desktopentry, icon, window class) keepego-lite-linuxon purpose, so existing installs are not orphaned.
| OS | Linux (primary), or native Windows 10/11 (beta). WSL is not required. |
| Node | 22 or newer for checkout installs; the packaged Windows setup bundles it. |
| Browser | Chrome, Chromium, Brave, or Edge. Linux searches PATH or EGO_LINUX_CHROME; Windows searches standard install paths. |
git clone https://github.com/opencue/agenticbrowser.git
cd agenticbrowser
sh skills/ego-browser/scripts/install.shThe installer checks Node and your browser, builds the harness, installs the MCP
runtime dependencies, links ego-browser and ego-browser-mcp into
~/.local/bin (override with EGO_LINUX_BIN_DIR), and runs diagnostics.
Doing it by hand
cd package/ego-browser && CI=true npm ci && CI=true npm run build
cd ../ego-linux && npm ci && npm test # verify the port: headless, throwaway profile
ln -s "$PWD/bin/ego-browser.mjs" ~/.local/bin/ego-browser
ln -s "$PWD/bin/ego-browser-mcp.mjs" ~/.local/bin/ego-browser-mcpCI=true is required, not cosmetic: the harness's prepare script runs
lefthook install, which fails on any machine with a global core.hooksPath,
and CI=true is that script's own escape hatch.
From a checkout, run the native PowerShell installer (no WSL needed):
git clone https://github.com/opencue/agenticbrowser.git
cd agenticbrowser
powershell -ExecutionPolicy Bypass -File .\skills\ego-browser\scripts\install-windows.ps1It builds the harness, installs per-user ego-browser.cmd and
ego-browser-mcp.cmd, updates the user PATH, and runs diagnostics without
opening the browser. Open a new PowerShell afterwards. Tagged releases also
attach a bundled ego-lite-setup.exe for machines without Node.
Five steps, one command each.
ego-browser --import-chrome-profileCopies the Default directory of your real Chrome, Chromium, Edge or Brave
profile into the agent's own profile, so cookies and logins carry into agent
tasks. Stop the backing browser first (ego-browser --stop) if it is running.
ego-browser --openA Chromium window appears. It is not your everyday browser: it runs from a
separate profile under ~/.local/share/ego-lite-linux/profile, has its own
window class, and its profile chip reads ego lite — agent, so you can always
tell which window an agent is driving. Run it again any time to raise it.
The interface is a heredoc of JavaScript on stdin, with every helper preloaded:
ego-browser <<'JS'
await page.goto('https://example.com')
console.log(await page.snapshot())
JSpage.snapshot() returns the semantic view of the page: the roles, accessible
names and @N refs a model reads to "see" it. From an agent CLI you normally
don't type this yourself; the agent loads the ego-browser skill and writes the
block for you:
ego-browser follow @someone on x.com for me
A task space is a named set of tabs with an owner. Spaces use the live agent
profile by default, so cookies, localStorage, IndexedDB and service-worker
state are shared everywhere you are signed in (see
below).
ego-browser <<'JS'
await taskSpaces.run('research task', async (task) => {
await page.goto('https://example.com')
console.log(await page.snapshot())
})
JStaskSpaces.run selects or creates the space and completes it when the callback
succeeds. For multi-step work, drive the lifecycle yourself:
| Call | Owner afterwards | What it means |
|---|---|---|
taskSpaces.useOrCreate(name) |
agent / unchanged |
Reuse the named space or create it; use this every round. A space you control is only selected (read-only) until a confirmed takeOver. |
taskSpaces.handOff(name) |
agentDelegatedToUser |
Pass it to you (login, captcha, manual confirmation). |
taskSpaces.takeOver(name) |
agent |
The agent takes it back, only after you confirm. |
taskSpaces.claim(id) |
agent |
Claim an existing space. |
taskSpaces.complete(name, {keep}) |
user / closed |
Done. keep: true leaves the tabs open as yours; false closes them. |
Spaces whose tabs you close by hand are reconciled away on the next call.
Ownership is enforced at the bridge. While you control a space, the agent's page operations fail with
EGO_TASK_SPACE_USER_IN_CONTROLuntil control is handed back.
The CLI also ships the newer upstream harness. It is chosen automatically when a
script calls taskSpace( or profiles(; everything above keeps running on v1.
ego-browser <<'JS'
const task = await taskSpace('research task')
const page = task.page('p1') // every new space opens with page p1
await page.goto('https://example.com')
console.log(await page.snapshot())
await task.finish({ keep: [] }) // or keep: ['p1'] to leave it open for you
JSPages get permanent labels (p1, p2, …); task.newPage() opens another and
task.handOff() passes the space to you. Set EGO_BROWSER_RUNTIME=v1 or v2
to force a runtime. Details: package/ego-linux/README.md.
ego-browser --install-desktop-entryWrites an XDG desktop entry and a scalable icon, then refreshes the desktop and
icon caches. Clicking it runs --launch, which opens each URL xdg-open passes,
or the Spaces overview with no arguments.
The entry pins the absolute path of the node that installed it, because a
desktop session's PATH is not your shell's: a node from nvm, fnm or asdf would
be invisible and the icon would fail silently. Re-run this after switching Node
versions.
A local stdio MCP server (modular @modelcontextprotocol/server v2 SDK)
negotiates the 2026-07-28 protocol with current clients and keeps the legacy
fallback for older hosts. Point your host at ego-browser-mcp with no arguments.
Codex (~/.codex/config.toml):
[mcp_servers.ego-browser]
command = "ego-browser-mcp"Claude Code:
claude mcp add ego-browser -- ego-browser-mcpThe server exposes one tool, ego_browser_run. Its script argument is the
same JavaScript you would send through a heredoc; timeoutMs is optional and
defaults to 120 seconds:
{
"script": "await page.goto('https://example.com'); console.log(await page.snapshot())",
"timeoutMs": 120000
}Each call runs through the CLI in an owned child process: protocol stdout stays separate from script output, calls on one connection are serialized, cancellation kills the child, and captured output is capped at 1 MiB.
Why one tool? Mirroring every helper as its own MCP tool would turn one
composable program back into a navigate → look → click → look chain, paying a
model round trip per step. One tool, one program keeps the same speed as the CLI.
Every heredoc is its own short-lived Node process. The browser, not the process, is what has to survive, so state lives in files.
flowchart LR
A["agent session<br/>Claude Code, Codex, ..."]
B["node process<br/>harness + CDP bridge<br/>exits when the block ends"]
C["Chromium<br/>one window, your imported profile<br/>persists between runs"]
F["~/.local/state/ego-lite-linux/<br/>task-spaces.json, browser.json"]
A -->|"heredoc on stdin"| B
B -->|"CDP over WebSocket"| C
B <-->|"reads / writes"| F
- One browser, reused. The first run launches Chromium with
--remote-debugging-port=0, reads the negotiated port fromDevToolsActivePortand records it. Later runs attach to that port if it answers, so consecutive commands see the same browser and tabs. - Page zoom is forced to 100%. An imported profile brings your zoom along; at 150% a 1280px window lays out as 853 CSS px, and coordinate clicks land on nothing.
- The window is 1280×900 at device scale factor 1, so layout doesn't depend on your desktop's HiDPI setting.
- Stale
SingletonLockis cleared before launch, so a browser killed without a clean shutdown doesn't block the next one with "Failed to create a ProcessSingleton". - Low memory → headless. If
EGO_LINUX_HEADLESSis unset and available memory is belowEGO_LINUX_LOW_MEMORY_MB(default 4096), the browser starts headless and trimmed.
Default task-space tabs live in the agent profile's default browser context. That
is the only stock-Chromium path that shares all login state live (cookies,
localStorage, IndexedDB, CacheStorage, service workers), so a login made in
one space is visible in the next without a copy step.
If storage isolation matters more than live logins, set
EGO_LINUX_TASK_SPACE_STORAGE=isolated. Each space then gets its own browser
context seeded with cookies only; non-cookie auth stores don't carry over. See
docs/isolation-with-inherited-logins.md.
Bridge internals, method by method, are in
package/ego-linux/README.md.
| Command | What it does |
|---|---|
ego-browser --status |
Connection state of the backing browser, as JSON. |
ego-browser --open |
Open or raise the shared agent browser window. |
ego-browser --launch [url|file …] |
Open each URL or file in a tab and raise the window; no arguments shows the Spaces overview. |
ego-browser --spaces |
Open the Spaces overview panel. |
ego-browser --doctor [--json] |
Inspect installation and runtime state without starting or attaching to the browser. |
ego-browser --cleanup-session |
Close this agent session's spaces and stop its recognised dev servers. |
ego-browser --stop |
Terminate the backing browser and clear its profile lock. |
ego-browser --import-chrome-profile |
Copy your real Chrome profile in, so agent tasks inherit your logins. |
ego-browser --install-desktop-entry |
Add it to your app launcher, with an icon. |
ego-browser --headless |
Run the backing browser headless. Only affects the first launch. |
ego-browser --help |
Usage. |
| Path | What |
|---|---|
~/.local/share/ego-lite-linux/profile |
The agent's browser profile, where imported Chrome data goes. |
~/.local/state/ego-lite-linux/ |
browser.json and task-spaces.json, the state shared across runs. |
~/.local/share/applications/ego-lite-linux.desktop |
The app launcher entry. |
~/.local/share/icons/hicolor/scalable/apps/ego-lite-linux.svg |
Its icon. |
Both roots follow XDG_DATA_HOME / XDG_STATE_HOME when set.
| Variable | Effect |
|---|---|
EGO_LINUX_CHROME |
Which browser binary to launch. |
EGO_LINUX_PROFILE |
Which profile directory to use. |
EGO_LINUX_CDP_URL |
Attach to an already-running DevTools endpoint instead of launching one. |
EGO_LINUX_BIN_DIR |
Where install.sh links the CLI. Defaults to ~/.local/bin. |
EGO_LINUX_HEADLESS |
1 launches headless by default; --open still gives a visible window. |
EGO_LINUX_LOW_MEMORY_MB |
Below this much available memory (default 4096) a launch is headless and trimmed; 0 turns it off. |
EGO_LINUX_TASK_SPACE_STORAGE |
isolated or isolated-sync for per-space browser contexts (cookies only). |
EGO_LINUX_CURSOR |
0 hides the agent cursor overlay in screenshots. |
EGO_BROWSER_ARTIFACT_TTL_HOURS |
How long screenshots, failure artifacts and temp download dirs are kept. Default 24 hours. |
| Symptom | Cause and fix |
|---|---|
Failed to create a ProcessSingleton |
A browser died without releasing SingletonLock. The launcher clears it automatically; if it persists, run ego-browser --stop. |
| Clicking the launcher icon does nothing | Usually a Node version switch; the entry pins an absolute node path. Re-run ego-browser --install-desktop-entry. |
no Chrome/Chromium binary found |
None of the candidates are on PATH. Set EGO_LINUX_CHROME to an absolute path. |
| No window appears | The browser is headless (an earlier --headless, EGO_LINUX_HEADLESS, or low memory). ego-browser --open swaps it for a visible one. |
npm ci fails in package/ego-browser |
A global core.hooksPath breaks lefthook install. Use CI=true npm ci. |
Two suites, run one at a time, since both drive a browser:
cd package/ego-linux && npm test # the bridge, headless, against a local fixture
cd package/ego-browser && npm run e2e # real-browser suite, needs ego-browser on PATHKnown flake: canvas drawing under load. The three canvas cases occasionally count one stroke too many.
driver/pointer.tsfinishDragProbewaits 50 ms for a trustedmouseupand re-synthesises the drag in JavaScript if it hasn't seen one; when the real events land late, the page gets both. Details indocs/canvas-drag-flake.md.
Bugs and feature requests: github.com/opencue/agenticbrowser/issues.
MIT. Originally derived from
citrolabs/ego-lite; its
Copyright (c) 2026 CitroLabs notice is retained as the license requires. This
project is not affiliated with or endorsed by CitroLabs.
