How to Set Up ego‑lite for Human‑Agent Collaboration: A Complete Guide

TL;DR: Install the native ego‑lite Chromium app, add the ego-browser skill via npx skills add citrolabs/ego-lite, and run /ego-browser with a heredoc script to let AI agents and humans share browser control through isolated task spaces with explicit handoff protocols.

Setting up ego‑lite for human‑agent collaboration requires coordinating three architectural layers: the native Chromium browser, a Node.js helper runtime, and a skill package that agents invoke. This guide walks through each step using actual source files from the citrolabs/ego-lite repository.

Prerequisites and Architecture Overview

ego‑lite consists of three cooperating layers that enable side‑by-side human and AI browser control:

Layer	Purpose	Key Source File
ego‑lite app	Native Chromium instance with access to user Chrome data (cookies, extensions, logins)	README.md at repo root
ego‑browser runtime	Node.js helper that exposes Playwright‑style facades (page, browser, taskSpaces) to agent scripts	package/ego-browser/src/helpers.ts
Skill package	Agent-facing manifest and documentation in the skills/ego-browser folder	skills/ego-browser/SKILL.md

The native app exposes a global ego runtime. The ego‑browser package wraps this bridge with developer‑friendly helpers that agents call from a Node.js heredoc.

Step 1: Install the ego‑lite Native App

Download the ego‑lite app as a native macOS DMG (Windows and Linux builds are planned). On first launch, the app prompts you to migrate your existing Chrome profile.

Accept this migration. Both you and the agent need access to the same logins, cookies, and extensions for seamless collaboration.

# macOS installation

# 1. Download from releases page

# 2. Drag ego-lite to Applications

# 3. Launch and approve Chrome profile migration

Detailed installation steps are documented in skills/ego-browser/references/install.md, referenced from the main SKILL.md file.

Step 2: Add the ego‑browser Skill to Your Agent

Install the skill package that teaches your agent how to invoke the browser:

npx skills add citrolabs/ego-lite

This command copies skill files—including the helper bundle from package/ego-browser/src/helpers.ts—into your local skill directory. The agent now recognizes the /ego-browser command.

Step 3: Run Your First Collaborative Task

Execute agent scripts through the CLI using a heredoc. The runtime injects helper facades and executes inside the ego‑lite process:

/ego-browser <<'EOF'
// Your agent script runs here with full access to ego helpers
EOF

The helpers in package/ego-browser/src/helpers.ts provide these core facades:

• page – Playwright-style page interactions (goto, click, fill, evaluate)
• browser – Browser‑level control (newPage, close)
• taskSpaces – Isolated tab management (useOrCreateTaskSpace, handOffTaskSpace, completeTaskSpace)
• site – Site‑specific learned tools
• fetch – Network requests through the browser context

Step 4: Create Isolated Task Spaces

Task spaces are the key isolation primitive. Each space gives the agent its own tab set while you continue using normal browser windows.

// Start or reuse a named task space for your goal
const task = await useOrCreateTaskSpace('research latest AI news');

// Open a dedicated tab for agent work
await openOrReuseTab('https://example.com', { wait: true });

// Capture semantic snapshot for the LLM to read
cliLog(await snapshotText());

The useOrCreateTaskSpace function and related helpers are implemented in package/ego-browser/src/helpers.ts. The design guarantees agents work from snapshots rather than polling the live page, eliminating token‑wasteful round‑trips.

Step 5: Implement Human Handoff for Manual Steps

When agents encounter captchas, login walls, or tasks requiring human judgment, explicitly transfer control:

// Agent detects captcha and hands off to human
await handOffTaskSpace(task.id);
cliLog('Please solve the captcha, then click "Continue".');

// After user confirms in UI, agent regains control
await takeOverTaskSpace(task.id);
// Or wait passively: await waitForAgentControl();

The handoff protocol is defined in skills/ego-browser/SKILL.md. The user's UI displays the same page; confirmation signals are bridged through the native ego runtime via CDP transport.

Step 6: Clean Up Task Spaces

Terminate collaboration cleanly with completeTaskSpace:

// Close the space and remove agent tabs
await completeTaskSpace(task.id, { keep: false });

// Or keep the page visible for user review
await completeTaskSpace(task.id, { keep: true });

Complete Working Example

// Full collaboration workflow
const task = await useOrCreateTaskSpace('research latest AI news');

await openOrReuseTab('https://example.com', { wait: true });
cliLog(await snapshotText());

await click('button.primary', { label: 'search' });

// Human-in-the-loop for captcha
await handOffTaskSpace(task.id);
cliLog('Please solve the captcha, then click "Continue".');

await takeOverTaskSpace(task.id);
await completeTaskSpace(task.id, { keep: false });

The snapshotText(), click(), and other facade methods wrap calls to globalThis.ego with thin CDP-based wrappers as implemented in package/ego-browser/src/helpers.ts.

Key Source Files Reference

File	What It Contains
README.md	High‑level ego‑lite overview, download links, quick‑start
package/ego-browser/src/helpers.ts	Helper façade implementation (page, browser, taskSpaces, etc.)
package/ego-browser/README.md	Build and test instructions for the runtime
skills/ego-browser/SKILL.md	Agent‑facing contract, usage examples, handoff protocol
skills/ego-browser/references/install.md	Native app installation guide
package/ego-browser/src/taskspace-e2e.test.mjs	E2E tests verifying task‑space lifecycle

Summary

• Install the native ego‑lite app and migrate your Chrome profile for shared credentials
• Add the skill with npx skills add citrolabs/ego-lite to enable /ego-browser commands
• Create isolated task spaces via useOrCreateTaskSpace for agent‑specific tab sets
• Hand off control with handOffTaskSpace when humans must intervene
• Resume with takeOverTaskSpace or waitForAgentControl after user confirmation
• Close cleanly using completeTaskSpace with optional { keep: true } for review

The architecture in citrolabs/ego-lite separates human UI from agent actions, uses snapshot‑based observation to reduce token costs, and provides explicit control transfer protocols proven in taskspace-e2e.test.mjs.

Frequently Asked Questions

Does ego‑lite work on Windows or Linux?

Currently, ego‑lite distributes as a macOS DMG only. Windows and Linux builds are planned according to the repository README. The skill package and helper runtime are platform‑agnostic Node.js code, so only the native Chromium wrapper requires porting.

Can multiple agents use the same task space simultaneously?

No. Task spaces enforce single‑control semantics. Either the agent holds control (after takeOverTaskSpace) or the user does (after handOffTaskSpace). The waitForAgentControl helper polls until control returns to the agent, preventing race conditions.

What happens to my Chrome data when I migrate?

The ego‑lite app reads your existing Chrome profile—cookies, localStorage, extensions, and logins—without modifying the original. This gives both you and the agent access to authenticated sessions. The migration is optional but recommended for productive collaboration.

How do I debug failing agent scripts?

Add cliLog(await snapshotText()) calls to inspect the semantic page snapshot at any point. The E2E tests in package/ego-browser/src/taskspace-e2e.test.mjs demonstrate verification patterns. For runtime issues, check that the native app is running and that globalThis.ego is defined in the injected context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}