How Ego-Lite Enables AI Agents to Inherit User Login States and Cookies

Ego-Lite maintains a persistent headless Chrome instance with a shared user profile, allowing AI agents to automatically inherit cookies and login sessions by re-attaching to the same Chrome DevTools Protocol (CDP) session instead of launching isolated browser contexts.

Ego-Lite is an open-source browser automation framework designed specifically for AI agent workflows. Unlike traditional automation tools that spawn ephemeral browser instances, ego-lite enables AI agents to inherit user login states and cookies through a shared persistent browser architecture that preserves authentication across multiple agent executions.

The Shared Browser Architecture

At the core of ego-lite's session inheritance is a single headless Chrome process that persists across agent executions. When an AI agent initiates a task, the runtime calls the ensureSession function in src/browser-runtime.ts to establish or recover a connection to the browser.

If an existing CDP session is already active, the runtime re-attaches to that session rather than launching a fresh browser process. Because Chrome maintains its user profile—including cookies, localStorage, and authentication tokens—within this persistent process, any agent attaching to the session immediately gains access to the stored login state without explicit credential passing.

How Session Persistence Works

The runtime tracks the active CDP connection through a singleton state object defined in src/state.ts. This state object stores the current session ID and snapshot cache, ensuring that subsequent agent calls reference the same browser context.

When helpers like nav, js, or fetch (exposed via src/helpers.ts) execute, they retrieve the active session from the global state and transmit commands through ego.sendCDPMessage. Since the underlying Chrome profile remains unchanged between agent runs, cookies set during a previous manual login or automated session are automatically available to the current agent without explicit configuration.

Practical Implementation: Accessing Inherited Cookies

AI agents can read inherited authentication state directly using JavaScript execution within the shared session. The following example demonstrates navigating to a protected resource and extracting the current cookies:

// Navigate to a site with existing login state
await nav('https://github.com/settings/profile');

// Extract cookies from the persistent session
const authCookie = await js('document.cookie');
console.log('Inherited auth cookie:', authCookie);

No explicit cookie management is required; the document.cookie call returns values from the shared Chrome profile automatically.

Using Inherited State for Authenticated Requests

Agents can leverage the inherited cookie string to perform authenticated HTTP requests through the fetch helper. This pattern allows seamless API access using the user's existing session:

// Retrieve cookies from the shared browser context
const cookies = await js('document.cookie');

// Execute authenticated API request using inherited credentials
await fetch('https://api.github.com/user', {
  headers: { 'Cookie': cookies }
});

The fetch command operates within the same CDP session managed by src/browser-runtime.ts, ensuring the request includes all relevant authentication headers from the inherited login state.

Key Source Files and Functions

• src/browser-runtime.ts: Contains the ensureSession function that manages CDP session lifecycle and enforces the singleton browser pattern.
• src/state.ts: Defines the global state object that persists the active CDP session ID and cache across agent invocations.
• src/helpers.ts: Exposes high-level agent functions including nav, js, and fetch that interface with the shared session.
• src/driver/nav.ts: Implements navigation commands that operate on the persistent browser context.

Summary

• Ego-lite uses a single persistent headless Chrome instance shared across all AI agents, eliminating the isolation typical of ephemeral browsers.
• The ensureSession function in src/browser-runtime.ts re-attaches to existing CDP sessions rather than spawning new browser processes.
• Login states and cookies persist in Chrome's user profile, accessible via the global state object in src/state.ts.
• Agents inherit authentication automatically through standard JavaScript APIs like document.cookie without manual cookie handling.
• The fetch, nav, and js helpers operate within the shared session context, enabling seamless authenticated workflows.

Frequently Asked Questions

How does ego-lite differ from isolated browser contexts like Puppeteer or Playwright?

Traditional tools like Puppeteer and Playwright launch isolated browser contexts or incognito profiles for each script execution, destroying cookies and login states upon completion. Ego-lite maintains a persistent Chrome process with a stable user profile, allowing agents to inherit existing authentication across multiple executions by re-attaching to the same CDP session.

Where are the cookies and login states physically stored?

Cookies and login tokens reside in the standard Chrome user profile directory used by the headless instance. Because ego-lite re-attaches to the same CDP session via ensureSession rather than launching new browser processes, the profile—including document.cookie, localStorage, and sessionStorage—remains intact between agent runs.

Can multiple AI agents access the same login session simultaneously?

Yes. Since all agents connect to the singleton browser instance tracked in src/state.ts, multiple agents can operate within the same browser context concurrently. They share the same cookies and storage state, though care should be taken to avoid race conditions when modifying shared resources.

Is there a way to clear or reset the inherited login state?

Resetting the state requires terminating the persistent Chrome process and clearing the user profile directory. Currently, ego-lite does not provide a built-in helper to programmatically clear cookies without restarting the underlying browser, as the architecture prioritizes session continuity over isolation.

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