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

> Learn to set up ego-lite for human-agent collaboration. This guide covers installing the Chromium app and configuring the ego-browser skill for seamless shared browser control.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) |
| **Skill package** | Agent-facing manifest and documentation in the `skills/ego-browser` folder | [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/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.

```bash

# 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`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md), referenced from the main [`SKILL.md`](https://github.com/citrolabs/ego-lite/blob/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:

```bash
npx skills add citrolabs/ego-lite

```

This command copies skill files—including the helper bundle from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

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

```

The helpers in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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.

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`:

```javascript
// 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

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts).

## Key Source Files Reference

| File | What It Contains |
|------|------------------|
| [`README.md`](https://github.com/citrolabs/ego-lite/blob/main/README.md) | High‑level ego‑lite overview, download links, quick‑start |
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Helper façade implementation (`page`, `browser`, `taskSpaces`, etc.) |
| [`package/ego-browser/README.md`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/README.md) | Build and test instructions for the runtime |
| [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) | Agent‑facing contract, usage examples, handoff protocol |
| [`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/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.