# Selector Forge

> AI-powered browser extension that generates and stress-tests reliable CSS and XPath selectors directly on live pages for scraping, testing, and automation.

Selector Forge is an open-source Chrome and Firefox browser extension built by Intuned (The Metrics Shop, Inc.) that generates reliable CSS and XPath selectors using AI. Instead of copying fragile selectors by hand, users point at any element on a live page and the extension proposes, tests, and re-verifies candidates against the real DOM before surfacing a result. The project is MIT-licensed and available on GitHub.

## What It Is

Selector Forge sits in the browser extension layer and solves a specific, recurring pain point for developers who write end-to-end tests, build scrapers, or automate web pages: static selectors break when pages change. The extension intercepts that problem at the source by generating selectors that are anchored to semantic context — labels, structure, and intent — rather than brittle positional attributes. It supports both single-element targeting and list-mode selection for repeating sets of items.

## How the Verification Loop Works

The trust boundary is a core design principle. The extension captures a compact snapshot of the user's picks (selected targets, DOM context, seed candidates) and sends it to Intuned's selector backend. The backend proposes and ranks candidates; the extension then tests every candidate against the live DOM and feeds results back. This loop repeats until the backend settles on a winner. Critically, the AI proposes and ranks — it never gets the final word on correctness. The browser is always the source of truth.

- **Single mode**: pick one element; get verified selector candidates for that exact target.
- **List mode**: pick two examples from a repeating set; get a verified container selector for the full set, previewed before saving.
- Over-matching and under-matching selectors are rejected during list verification.

## Architecture and Tech Stack

The extension is built on WXT (a modern browser extension framework) with React for the popup UI, and targets Manifest V3 for both Chrome and Firefox. The project layout separates concerns cleanly: a background service worker handles session state and the agent loop; a content script manages the picker overlay, DOM access, and selector testing; and the popup handles mode controls, results, and copy actions. A typed, direction-partitioned runtime-message protocol connects these contexts. The repository includes unit tests (Vitest), browser-mode tests that run selector generation against a real DOM, and Playwright E2E tests against the packaged extension.

## Roadmap and Current Direction

The README describes several planned capabilities:
- **CLI control** via `npx intuned forge pick` — foundational wiring (the `tabs` permission and CDP-driven session start) is already in place.
- **Smart picker** with a `multiple` mode and AI field detection that suggests useful fields and selectors automatically.
- **Drill-down modes** for precision refinement after a pick, including XPath/DOM tree walking and parent/child level adjustment.
- **Bring your own backend** — a planned self-hostable reference backend that replaces the Intuned cloud dependency entirely, including an open-source agent for selector generation.

Further out: selector/automation history, export to Playwright or plain JavaScript, automatic pagination detection, and cross-iframe/shadow-DOM support.

## Update: v0.0.5

The project was created in June 2026 and reached v0.0.5 on June 23, 2026. The free tier offers 200 selectors per month; unlimited usage is available on any Intuned plan. The homepage notes a Firefox add-on is available alongside the Chrome Web Store listing, and a CLI interface is listed as coming soon.

## Features
- AI-generated CSS and XPath selectors
- Live DOM re-verification before surfacing results
- Single element selection mode
- List mode for repeating element sets
- Anchors selectors to semantic labels, not position
- Chrome and Firefox support (MV3)
- Over-matching and under-matching rejection for list selectors
- Copy selector with one click
- Open-source MIT-licensed codebase
- CLI integration coming soon (npx intuned forge pick)

## Integrations
Playwright, Chrome, Firefox, Intuned backend, WXT framework

## Platforms
API, BROWSER_EXTENSION, CLI

## Pricing
Open Source, Free tier available

## Version
v0.0.5

## Links
- Website: https://selectorforge.ai/
- Documentation: https://github.com/Intuned/selector-forge/blob/main/ARCHITECTURE.md
- Repository: https://github.com/Intuned/selector-forge
- EveryDev.ai: https://www.everydev.ai/tools/selector-forge