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

> Discover how Ego-Lite enables AI agents to inherit user login states and cookies by sharing a persistent headless Chrome instance and CDP session. Streamline your AI browser automation.

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

---

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

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

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)**: Contains the **`ensureSession`** function that manages CDP session lifecycle and enforces the singleton browser pattern.
- **[`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts)**: Defines the global **`state`** object that persists the active CDP session ID and cache across agent invocations.
- **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)**: Exposes high-level agent functions including **`nav`**, **`js`**, and **`fetch`** that interface with the shared session.
- **[`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.