Primary question: Do you need your agent to act inside your already-logged-in browser, instead of driving a separate headless instance with fresh credentials?
RepoDaily adoption score
RepoDaily rates this as 88/100 (strong) for adoption: evidence, installation path, production risk, differentiation, license clarity, and AI/agent fit are scored from the article sources and adoption notes.
4 source(s) across 3 source category/categories, plus a RepoDaily-specific evidence module when available.
6 workflow step(s), 4 next-action step(s), and 4 command/install signal(s) were detected.
Trending momentum is +884 stars, with maintenance/release/issue signals counted when present.
Risk is marked medium, with 4 security note(s) and 3 explicit skip condition(s).
2 opportunity lens item(s), 3 alternative(s), and 4 type-specific section(s) support differentiation.
License source or license wording is present.
6 AI/agent-related signal(s) were detected in the article text and metadata.
Project overview
ego-lite is citrolabs' answer to a specific pain point: when an AI agent needs to do something on the web, it usually has to spin up its own browser, log in from scratch, and fight the human user for tab focus. The repository packages a Node.js helper runtime and an agent skill package that sit on top of a separate Chromium-derived browser app called ego. The pitch is that your agents and you work in parallel — they run isolated Spaces while your tabs stay yours.
The project does not ship the browser binary in this repo. According to CONTRIBUTING.md, `ego-browser` is the Chromium browser, while `ego-lite` is the Node.js helper runtime and agent skill package that run on top of it. The macOS DMG is downloaded from cdn.ego.app, and the skill is wired into your machine via `npx skills add citrolabs/ego-lite` or through the app installer. On first launch the app asks one question — whether to migrate Chrome data — and if you say yes, your logins, cookies, extensions, and bookmarks move over.
Under the hood the runtime is TypeScript targeting Node.js >= 22 in ESM mode. Agents invoke the CLI by running `ego-browser nodejs <<'EOF' ... EOF` from inside the browser, and each heredoc runs in a fresh Node process with all helpers injected into scope. State such as task spaces, tabs, and login sessions lives on the browser side, not in the Node process, which keeps the helper thin and lets the browser own the security-critical session data.
The README positions ego-lite against browser-use and agent-browser, calling those frameworks that need a separate browser to drive. Whether that framing is fair, the architectural difference is real: ego-lite is one browser designed for sharing, not a driver attached to an unrelated browser. That distinction shapes the trade-offs below.
Why it is trending now
- 884 period stars and trending rank 6 on 2026-07-25, driven by demand for agents that reuse human browser sessions instead of starting fresh.
- Direct integration story for named agents — the README cites Codex and Claude Code as targets, and the repo includes a `.claude-plugin/` marketplace manifest.
- Zero-config onboarding: one Chrome-migration prompt, one `/ego-browser` invocation, and the agent inherits authenticated state.
- MIT-licensed runtime with an npm-installable skill package (`npx skills add citrolabs/ego-lite`), lowering the barrier for agent-first users.
Problem it solves
- Existing automation frameworks drive a separate browser, so logins do not carry cleanly and the agent starts unauthenticated.
- Human and agent often fight for the same tab or window when sharing one browser instance.
- Per-site quirks — selectors, login flows, cookie walls — have to be rediscovered by every new agent run.
- Re-authenticating inside an agent context is both slow and a credential-handling hazard.
How it works
- Install the ego lite macOS app from cdn.ego.app (Apple Silicon or Intel DMG), or run `npx skills add citrolabs/ego-lite` to add only the skill.
- On first launch, accept the Chrome data migration prompt so logins, cookies, extensions, and bookmarks transfer into ego.
- The installer places the `ego-browser` skill into every agent's skills directory on the machine.
- In your agent CLI, invoke `/ego-browser` followed by a plain-language instruction, for example `ego-browser follow @ego_agent on x.com for me`.
- The agent picks up the skill, opens the page inside an isolated Space, and runs a Node heredoc through `ego-browser nodejs <<'EOF' ... EOF` with helpers injected into scope.
- Task state — spaces, tabs, sessions — is held by the browser, while the Node process stays ephemeral and is discarded after each heredoc.
Architecture Read: What the Repo Actually Contains
The repository is split into two surfaces. `package/ego-browser/` is the runnable npm package written in TypeScript: it boots via `src/index.ts`, executes stdin through `src/run.ts`, composes the helper surface in `src/helpers.ts`, and talks to the browser over CDP via `src/browser-runtime.ts`. Element resolution is centralized in `src/element-resolver.ts`, supporting `@eN` references alongside CSS, XPath, and ARIA selectors.
Capability drivers live under `src/driver/` — `pointer.ts` for click/hover/drag/scroll, `keyboard.ts` for typing and key dispatch, `nav.ts` for page and tab navigation, `observe.ts` for snapshots and screenshots, `waits.ts` for wait primitives, and `files.ts` for uploads. A `src/learning/` module loads and validates per-site knowledge packs.
The second surface is `skills/ego-browser/`, the agent skill package. It ships `SKILL.md` and `SKILL.zh.md` usage guides plus `learnings/<site>/` packs for sites including github, google, and x-com. CONTRIBUTING.md is explicit that the browser binary is not in this repo — this is the helper runtime and skill layer only.
Try-It Path: Minimal Path to a Working Task
- Runtime requirement: Node.js >= 22, ESM, on macOS.
- Fastest path: download the Apple Silicon or Intel DMG from cdn.ego.app, install, and accept the Chrome migration prompt.
- Skill-only path: `npx skills add citrolabs/ego-lite` adds the ego-browser skill without the app; the app is installed on first task run.
- Agent-driven path: paste `Set up ego lite for me: https://github.com/citrolabs/ego-lite` and let the agent read `skills/ego-browser/references/install.md`.
- Validation command pattern: `/ego-browser <plain-language task>` from the agent CLI; the repo's example is `ego-browser follow @ego_agent on x.com for me`.
Integration Surface: How Agents Talk to the Browser
Agents communicate with ego through a heredoc protocol: `ego-browser nodejs <<'EOF' ... EOF`. CONTRIBUTING.md states that each heredoc runs in a fresh Node process with all helpers injected into scope, so there is no long-lived JS context to corrupt between tasks.
The helper surface includes `cdp()` and `js()` helpers (from `src/cdp-eval.ts`) for direct browser-side evaluation, plus higher-level drivers for pointer, keyboard, navigation, observation, waits, and files. Site-specific behavior is loaded from `learnings/<site>/` packs, which means recurring sites like github, google, and x-com can ship hand-curated selectors and flows instead of relying on generic resolution.
A `.claude-plugin/` directory in the repo root carries a Claude Code plugin marketplace manifest, which is the concrete mechanism behind the README's Claude Code compatibility claim.
Maintenance Risk: Signals from the Repo
- Platform coverage is narrow: macOS only at publish time; Windows and Linux are listed on the roadmap at lite.ego.app/roadmap.
- Browser binary is closed and distributed via cdn.ego.app DMGs — the open-source repo is the runtime and skill layer, not the browser itself.
- No published test results, coverage numbers, or release cadence visible in the source pack; CI is declared as `.github/workflows/ci.yml` running `node --test` suites.
- Per-site learnings for github, google, and x-com will rot when those sites change their DOM, and the maintenance burden scales with the number of supported sites.
Who should pay attention?
Good fit if
- You run Claude Code, Codex, or a similar agent on macOS and want it to act inside your authenticated browser.
- You repeatedly automate the same handful of sites (github, google, x.com) and would benefit from curated site learnings.
- You want agents to work in parallel with you, not take over your active tab.
Skip for now if
- You are on Windows or Linux — not supported today, only on the roadmap.
- You need a fully open-source browser stack — the ego browser binary itself is not in this repo.
- You require headless server-side automation with no local GUI browser.
Risks and cautions
Promising architecture and clean skill packaging, but macOS-only today, dependent on a closed browser binary, and reliant on per-site learnings that can rot.
- Browser binary is not open in this repo; trust depends on CitroLabs' DMG distribution from cdn.ego.app.
- Windows and Linux are roadmap items, limiting team-wide rollout.
- Site learnings for github, google, and x-com are fragile to upstream UI changes.
- Node.js >= 22 requirement may exclude older agent runtimes.
- Migrating Chrome data hands cookies, sessions, extensions, and bookmarks to ego — treat the ego app as a full browser from a credential-trust standpoint.
- Agent heredocs execute via `ego-browser nodejs <<'EOF' ... EOF` with helpers injected into scope; any prompt-injected instruction inside the page can influence that code path.
- The browser holds login session state on the browser side, which is safer than passing credentials through the Node process, but it also means a compromised Space can reach authenticated sessions if isolation is weak.
- MIT License applies to this repo only; the browser binary's license is separate and not covered by the source pack.
Alternatives to compare
| Approach | When to use | Trade-off |
|---|---|---|
browser-use | When you want an open-source automation framework that drives an external browser and you do not need to share your personal logged-in state. | Open source. |
| When you need cross-platform, scriptable browser automation with mature multi-browser support and no requirement to share human sessions. | Open source. | |
Agent-side browser extensions | When you want the agent to act inside an existing Chrome instance without installing a separate browser app. | Varies. |
What this trend reveals
Site-learning packs as a moat
The `learnings/<site>/` directory already curates behavior for github, google, and x-com. Contributors who add high-quality packs for high-traffic enterprise SaaS apps could make ego-lite the default for agent automation in those environments.
Check whether the existing learnings format in `skills/ego-browser/learnings/` can encode login, search, and navigation flows for your top three internal tools without code changes.
Claude Code plugin marketplace entry
The `.claude-plugin/` manifest positions ego-lite inside Claude Code's plugin marketplace. A polished plugin listing with demo tasks could capture developer mindshare ahead of Windows and Linux support landing.
Install via the Claude Code plugin path, run one task end-to-end, and time the difference versus a fresh-login Playwright script.
RepoDaily verdict
ego-lite's real contribution is architectural: it treats the browser as shared infrastructure with a Node.js helper runtime, not as a puppet to drive from outside. The TypeScript package is clean, the heredoc execution model is sensible, and the site-learning packs are a differentiated asset. The caveat is weight — macOS only, a closed browser binary, and per-site packs that will need active maintenance. Worth integrating today if you live in Claude Code on macOS; worth tracking otherwise.