Talox

Dependencies explained

Talox ships two browser automation packages:

Talox uses playwright-core with channel: "chrome" for maximum stealth — system Chrome provides a real browser fingerprint. The 19-layer JS stealth stack is injected via addInitScript before any page scripts run.

import { TaloxController } from 'talox';

// v4: config object as first arg
const talox = new TaloxController({ headless: true });

await talox.launch('my-agent', 'ops');

const state = await talox.navigate('https://example.com');

// Talox returns structured JSON — no HTML parsing needed
console.log('Title:', state.title);
console.log('Interactive elements:', state.interactiveElements.length);
console.log('Layout bugs detected:', state.bugs.length);

await talox.stop();

See examples/minimal-agent.ts for a copy-paste starting point.

Install Playwright Chromium (first time or on a new server)

npx playwright install chromium --with-deps ```

VPS / Headless Server Setup

Playwright's Chromium requires system dependencies that aren't present on a bare Linux VPS. Run this once after install:

npx playwright install chromium --with-deps

Talox defaults to headless: true, so no display server is needed. The required Chromium flags (--no-sandbox, --disable-dev-shm-usage) are set automatically.

All features work fully headless — including screenshots, visual diff (Pixelmatch/SSIM), OCR (Tesseract.js), and GhostVisualizer. None of these require a display; they operate on pixel buffers and pure JS.

If you're on a low-memory VPS (< 1GB), set PLAYWRIGHT_CHROMIUM_SANDBOX=0 as an environment variable as well.

---

Quick Start

npm package coming soon. For now, install directly from GitHub:

```bash git clone https://github.com/AVANT-ICONIC/Talox.git cd Talox npm install npm run build

Use Cases

• AI agent browsing — give your agent a persistent, stateful browser with structured output
• QA automation — detect layout bugs, JS errors, and visual regressions automatically
• Observe-driven testing — AI agent explores UI, annotates issues, generates PR-ready reports

---

Browser Lab Demo

examples/browser-lab.ts walks through a sandbox profile that:

• launches PRESETS.observe with headed overlay/recording enabled,
• exercises every practical tool (background tab, API capture, Markdown snapshot, search, structured content), and
• writes the generated Markdown/JSON report artifacts into talox-sessions/ (useful as a sanity check after npm install && npm run build + npx playwright install chromium).

Run the demo to validate the packaged presets, tools, and reporting output in one headed experiment.

---

Talox CLI & Packaging

npm package coming soon. Until then, run the CLI from the repo: node dist/cli/talox.js observe --help

• node dist/cli/talox.js observe starts the human-visible observe mode with headed browser, overlay, Markdown/HTML reporting, and the window.__taloxEmit__ bridge so you can annotate interactions while the agent runs.
• node dist/cli/talox.js run starts the autonomous task execution loop with an LLM planner for self-driving browser workflows.
• node dist/cli/talox.js skill create interactively creates a new SKILL.md file for per-site strategies.
• node dist/cli/talox.js init (aka the create-talox-app workflow) scaffolds a clean talox-app starter project with PRESETS.observe, ts-node/typescript tooling, Playwright install scripts, and examples/browser-lab.ts.
• Exported presets (ops, qa, observe, research, login-heavy) live in src/presets.ts so you can reuse curated verbosity, headedness, and human-takeover posture with a single spread or merge.
• The practical tools from getPracticalTools(talox) demonstrate background tabs, API response capture, Markdown snapshot export, on-site search, and visible structured content extraction, so your packaged profiles already include actionable browser lab helpers.

Codex CLI wrapper

Write a small script that uses TaloxController, then execute it with npx codex run scripts/codex-talox.mjs so Codex orchestrates Talox like any other skill.

import { TaloxController } from 'talox';

const talox = new TaloxController('./profiles');
await talox.launch('codex-agent', 'ops');
const state = await talox.navigate('https://example.com');
console.log(JSON.stringify(state, null, 2));
await talox.stop();

Codex can read the printed JSON, pass it into its function-calling loop, or pipe it into another skill for further analysis.

New CLI commands

talox run              # Start an autonomous task execution loop
talox skill create     # Interactively create a new skill file

---

Agent-Friendly API

Integrations

Talox ships as a flexible Node package with a CLI-first philosophy. The most efficient way to use Talox is through the CLI or direct Node.js scripting — no context-window bloat from MCP servers. For the community, an MCP server is also available for agents that prefer tool-use protocols.

Key components

Event-Driven Workflows

talox.on('navigation', (event) => console.log('Navigated to:', event.data.url));
talox.on('consoleError', (event) => console.log('Error:', event.data.error));
talox.on('bugDetected', (event) => console.log('Bug:', event.data));

From the repo (npm package coming soon)

node dist/cli/talox.js observe --profile my-observe-run --class qa --browser chromium --output-dir ./talox-sessions --format both ```

That command opens a headed Chromium session with the overlay + annotation buffer already armed, logs console/network errors, and writes JSON/Markdown reports. Run talox observe --help to tune the profile class, browser, verbosity, or report directory without touching code.

Each session now lives inside its own subfolder under the configured output directory (default talox-sessions/session-{id}-{timestamp}). The folder contains report.json, report.md, report.html, timeline.json, event-log.json, failures.json, diffs.json, bugs.json, and trace.json, along with a screenshots/ directory for before/after snapshots. The HTML report surfaces the timeline, event log, diffs, bug summaries, and artifact trace so you can understand why clicks, selectors, or adaptations behaved the way they did.

This produces a Markdown report with every issue attached to the specific element where it was found — something impossible with traditional assertion-based tests.

---

Talox vs other runner stories

Talox's mission is to be the obvious local-first browser runtime. The table below contrasts that focus with other well-known agent/browser automation options so the positioning stays sharp.

---