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

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 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, 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, 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 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 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:

// 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 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:

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:

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 calls ego.sendCDPMessage to transmit Chrome DevTools Protocol commands to the binary, while 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, 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, 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.

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