Usage

Minimal example

Save as agent.ts and run with npx tsx agent.ts:

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);

The agent launches Chrome, takes screenshots at each step, reasons about what it sees, and returns the final answer as result.result.

Streaming events

Use agent.stream() to receive typed StreamEvent objects as the agent runs:

import { Agent } from "@omxyz/lumen";

const agent = new Agent({
  model: "anthropic/claude-sonnet-4-6",
  browser: { type: "local" },
  instruction: "Search Wikipedia for 'browser automation' and return the first sentence.",
});

for await (const event of agent.stream()) {
  if (event.type === "step") {
    console.log("Step:", event.action);
  }
  if (event.type === "done") {
    console.log("Result:", event.result);
  }
}

Key configuration options

Option	Type	Default	Description
model	string	required	Provider and model, e.g. "anthropic/claude-sonnet-4-6"
browser.type	"local" or "cdp" or "browserbase"	required	Where to run Chrome
browser.headless	boolean	false	Run without visible window
maxSteps	number	30	Maximum perception-action steps
thinkingBudget	number	0	Extended thinking token budget
confidenceGate	object	off	Multi-sample validation on uncertain steps
policy	object	off	Domain allowlist / blocklist
verbose	0, 1, or 2	0	Logging level (0 = silent, 2 = full)
compactionThreshold	0-1	0.8	Context summarization trigger fraction
checkpointInterval	number	5	Browser state snapshot every N steps
siteKB	object	off	Domain-specific navigation tips injected into the prompt

Debug logging

LUMEN_LOG=debug npx tsx agent.ts        # All debug surfaces
LUMEN_LOG_ACTIONS=1 npx tsx agent.ts    # Action dispatch only
LUMEN_LOG_CDP=1 npx tsx agent.ts        # Chrome DevTools Protocol traffic
LUMEN_LOG_LOOP=1 npx tsx agent.ts       # Perception loop internals