# Role of the ego-lite macOS Application in the Ego-Lite Architecture

> Discover the ego-lite macOS application's role in the ego-lite architecture. It hosts the CDP harness, manages Task Spaces, and connects the ego-browser skill to your browser environment.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: architecture
- Published: 2026-08-26

---

**The ego-lite macOS application serves as the runtime host that executes the CDP harness, manages isolated Task Spaces, and bridges the open-source ego-browser skill to the actual browser environment.**

The `citrolabs/ego-lite` repository provides the open-source runtime and skill definitions for the ego-lite ecosystem, but the macOS application itself is the closed-source distribution channel that embeds this runtime and exposes it to AI agents. Understanding how this binary integrates with the repository code is essential for developers building browser automation workflows.

## Runtime Host and CDP Harness

The macOS application functions as the **browser host** that bundles its own `ego-browser` binary. This binary embeds the open-source runtime found in `package/ego-browser/src/` and supplies the **global object** `globalThis.ego` that helper functions communicate with via `ego.sendCDPMessage`.

### The ego-browser Binary

When you install the ego-lite macOS application, it deploys a closed-source `ego-browser` binary that acts as the actual browser engine. According to the project documentation, this binary implements the Chrome DevTools Protocol (CDP) transport layer and manages browser sessions. The open-source code in [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) implements the client-side logic that routes commands through this binary, but the binary itself handles the low-level CDP execution.

### Global Runtime Interface

The communication bridge between agent scripts and the browser happens through `globalThis.ego`. In [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), the `helperContext` object wraps calls to `ego.sendCDPMessage`, allowing agents to execute CDP commands without managing the protocol directly. This design ensures that the macOS app controls the browser state while the open-source skill provides a clean JavaScript API.

## Skill Integration and Distribution

The macOS application automates the deployment of the ego-browser skill to the local environment, eliminating manual configuration steps for end users.

### Automatic Skill Injection

Upon installation, the macOS app automatically adds the `ego-browser` skill to every user’s `skills/ego-browser` directory. As documented in [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md), this exposes helper functions—such as `snapshot`, `click`, and `navigate`—that agents invoke in their JavaScript execution context. The skill references in [`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md) specifically point to the macOS `.dmg` as the required runtime, confirming that the application is not merely a client but a mandatory dependency for the skill to function.

### macOS-Only Distribution Model

Currently, the macOS `.dmg` package is the sole distribution channel for the browser runtime. The [`README.md`](https://github.com/citrolabs/ego-lite/blob/main/README.md) indicates that Windows and Linux support is planned but not yet released, making the macOS application the exclusive gateway for running ego-lite agents against a real browser environment.

## Task Space Management

The application creates **isolated browsing contexts** called Task Spaces that allow agents to operate independently of the human user’s tabs.

### Isolated Browsing Contexts

Each Task Space represents a separate browsing context with its own cookies, storage, and execution environment. Agents create these spaces using the `newTaskSpace` helper, and the macOS app instantiates a new isolated browser profile behind the scenes. This isolation prevents agent actions from interfering with the user’s personal browsing session while maintaining full CDP access for automation tasks.

### Ownership and Claiming Semantics

The macOS runtime enforces strict ownership rules for Task Spaces. When a human user creates a space, agents cannot immediately manipulate it. Instead, the agent must call `claimTaskSpace` to request control, as implemented in the helper logic. This security boundary ensures that automated scripts cannot accidentally (or maliciously) interact with user-owned browsing sessions without explicit permission.

## Practical Implementation Examples

The following examples demonstrate how agent scripts interact with the macOS application’s runtime through the ego-browser skill.

### Executing a Basic Agent Workflow

This script runs inside the macOS app’s browser context, utilizing the injected `globalThis.ego` object to execute CDP commands:

```javascript
// Agent-side script executed by the macOS runtime
await navigate("https://example.com");
const btn = await query("loc=css:button.submit");
await click(btn);
await waitForNavigation();

```

The `navigate`, `query`, and `click` functions are defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) and rely on the macOS binary to transmit CDP messages to the actual browser instance.

### Creating Isolated Task Spaces

Agents can spawn dedicated environments for specific automation tasks:

```javascript
const space = await newTaskSpace("news-scraper");
await useTaskSpace(space);
await navigate("https://news.ycombinator.com");

```

Here, `newTaskSpace` triggers the macOS application to initialize a new browser context, while `useTaskSpace` switches the agent’s execution context to that isolated environment.

### Claiming User-Owned Spaces

When interacting with spaces created by the human user, the agent must explicitly claim ownership:

```javascript
await claimTaskSpace("my-personal-space");
await navigate("https://github.com");

```

This pattern enforces the ownership semantics documented in the architecture, ensuring the macOS application validates the agent’s right to control the specified Task Space before executing navigation commands.

## Summary

- The **ego-lite macOS application** is the closed-source runtime host that bundles the `ego-browser` binary and executes CDP commands.
- It provides the **`globalThis.ego`** object that bridges the open-source helpers in `package/ego-browser/src/` to the actual browser engine.
- The app automatically installs the **`ego-browser` skill** to the `skills/ego-browser` directory, exposing automation helpers to agents.
- It creates and manages **isolated Task Spaces**, allowing agents to browse independently of user tabs while enforcing ownership via `claimTaskSpace`.
- Currently, the macOS **`.dmg`** is the only supported distribution channel, making the application mandatory for running the ego-lite architecture.

## Frequently Asked Questions

### What is the role of the ego-lite macOS application in the architecture?

The macOS application serves as the **runtime host** and browser engine for the ego-lite ecosystem. It bundles the `ego-browser` binary that implements the CDP harness, manages Task Spaces, and executes the JavaScript helper functions defined in the open-source repository. Without this application, the `ego-browser` skill cannot function, as it relies on the binary’s `globalThis.ego` interface to communicate with the browser.

### How does the macOS app communicate with the open-source runtime?

The communication occurs through the **`globalThis.ego`** global object injected by the macOS binary into the JavaScript execution context. The open-source code in [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) calls `ego.sendCDPMessage` to transmit Chrome DevTools Protocol commands to the binary, while [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) provides the high-level API that agents use to interact with this interface.

### Is the ego-lite browser available on Windows or Linux?

No. According to the [`README.md`](https://github.com/citrolabs/ego-lite/blob/main/README.md), Windows and Linux support is planned but not yet released. The macOS `.dmg` package is currently the **only** distribution channel for the browser runtime, making macOS a mandatory requirement for deploying the ego-lite architecture in production environments.

### How do agents interact with browser elements through the macOS app?

Agents invoke helper functions—such as `navigate`, `query`, `click`, and `snapshot`—that are automatically exposed when the macOS app installs the `ego-browser` skill. These functions, defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), translate high-level automation commands into CDP messages sent via the macOS binary’s `ego.sendCDPMessage` method, allowing agents to drive the browser without directly managing protocol details.