Lumen
Lumen is a vision-first browser agent that operates by taking screenshots and sending them to a language model to decide actions, without relying on DOM scraping or selectors. It solves the problem of brittle web automation by using a self-healing, deterministic replay approach. It is intended for developers who need to automate complex browser tasks reliably, such as testing, data extraction, or workflow automation.
✨ Key features
- Vision-only loop: screenshot → model → action(s), no DOM scraping.
- Multi-provider support: Anthropic, Google, OpenAI, and OpenAI-compatible endpoints.
- History compression with tier-1 screenshot compression and tier-2 LLM summarization.
- Unified coordinates: ActionDecoder normalizes provider formats to viewport pixels.
- Persistent memory via writeState for structured JSON that survives compaction.
- Streaming events for real-time UI updates.
🎯 Use cases
- Automating web tasks like searching, form filling, and navigation.
- Building browser-based agents for testing or QA.
- Extracting data from websites that require complex interactions.
- Creating personal automation workflows for repetitive online tasks.
- Evaluating browser agent performance on benchmarks like WebVoyager.
📦 Installation
🧰 Requirements: Requires Node.js ≥ 20.19 and Chrome/Chromium for local browser mode. API keys for model providers (Anthropic, Google, OpenAI) are needed unless using a custom endpoint.
npm install @omxyz/lumen
🚀 Usage
import { Agent } from "@omxyz/lumen";
const result = await Agent.run({
model: "anthropic/claude-sonnet-4-6",
browser: { type: "local" },
instruction: "Go to news.ycombinator.com and tell me the title of the top story.",
});
console.log(result.result);
⚠️ Good to know
The README notes that the package is ESM-only, and the only error that throws is BROWSER_DISCONNECTED; other action errors are fed back to the model. It also mentions that Chrome may fail to launch on Linux CI without --no-sandbox.
❓ FAQ
What model providers are supported?
Lumen supports Anthropic, Google, OpenAI, and any OpenAI-compatible endpoint via a custom adapter. You specify the model as provider/model-id.
How do I resume a session?
You can serialize the agent state to JSON with agent.serialize(), save it, and later restore it with Agent.resume(data, options).
What are the safety features?
Lumen provides SessionPolicy for domain allow/block lists, PreActionHook for imperative denial, and Verifier as a completion gate to ensure the task is actually done.
How do I debug issues?
You can use environment variables like LUMEN_LOG=debug for all surfaces, or specific ones like LUMEN_LOG_ACTIONS=1 for action dispatch, LUMEN_LOG_CDP=1 for CDP traffic, and LUMEN_LOG_LOOP=1 for loop internals.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.