// Hercules 2.0 · open-source QA engine //

AI Test Agents Burn Tokens On Every Click. Hercules Runs On Your Laptop.

Write end-to-end tests in plain language. Hercules runs them in a real browser with a local model, checks every expected outcome, and keeps a screenshot and evidence for every step, with no selectors to maintain and nothing leaving your machine unless you allow it.

Web UIAPIsDatabasesMobileAccessibilitySecurity
$ uvx testzeus-hercules
localhost:7373 · Hercules tester UI
Hercules tester UI showing a passed run, each step's screenshot and the decision inspector with the model's confidence per element
✓ PASSED 4/4 steps · 2/2 assertions
Decider: local model · cost $0

Hercules picks a hardware tier from your memory · Gemma 4 on Ollama, LM Studio, llama.cpp, vLLM or MLX · macOS & Linux

  1. 16 GBfloor · Gemma 4 E4B
  2. 24 GBstandard · Gemma 4 26B-A4B
  3. 32 GBrecommended · 32K contextSweet spot
  4. 48 GB+comfortable · 2 parallel runs
// The AI testing problem //

Your Test Agent Is Expensive, Slow, And Hard To Trust

01

Tokens Burned On Every Step

Agents that replay the whole page to a large model on every turn turn each test run into an API bill, and each regression cycle into a budget line.

02

Selectors That Move

Scripted suites break when an ID, class or layout changes. Someone has to babysit locators instead of testing the product.

03

Passes You Can't Explain

A model said "looks good". Without a plan, recorded assertions and evidence per step, a green run is a guess you can't audit.

04

Data That Leaves The Building

Cloud-only agents send page content and screenshots off your machine. Regulated and air-gapped teams can't use them at all.

// The Hercules answer //

Models Read. Code Executes.

Hercules has no rule-based step reader and no coded decider. A language model reads your steps, a decider answers short typed questions (which element, which tool, did it work), and deterministic code runs the action and checks what the page actually shows. When a model isn't sure, the result is unverified or a retry. Code never guesses.

  • Plain-language steps, no selectors. The page becomes a numbered Set-of-Mark list; the decider picks an element, Playwright acts on it.
  • A plan before every run. Actions, success criteria, risks and lint, reviewed before the browser opens.
  • Strict verdicts. Every expected outcome is recorded; a run passes only when nothing stayed unverified.
  • Evidence for every step. Screenshots, decisions and observations in .hercules/runs/<run_id>/.
// Built for engineering teams //

Three Things Cloud-Only Test Agents Cannot Do

/// 01

Run Fully On Your Hardware

Point Hercules at any OpenAI-compatible endpoint. On a 32 GB MacBook Pro, Gemma 4 on Ollama reads steps and makes every decision, with no API bill.

  • Pure mode: local model or a local Clef server decides
  • Egress local: nothing leaves, telemetry off
  • Secrets passed by variable name, masked in evidence
/// 02

Work Inside Your Coding Agent

Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI call Hercules over MCP, then write a case, run it in a real browser and fix the code from the failing step.

  • hercules init --agent claude
  • Reads failing step + screenshot
  • Exploratory bug hunts from a prompt
/// 03

Hand You Real Code

Turn a passed run into Playwright Test or pytest-playwright with locators proven unique on the live page. It runs with no Hercules and no model at test time.

  • hercules export --check
  • Frames and shadow DOM included
  • Run on BrowserStack, Sauce Labs or TestMu AI
Pure mode100% local

The local model reads the steps and makes every decision (or a local Clef server decides). Pair with --egress local for air-gapped teams.

Hybrid modewith an OpenRouter key

Your local model reads; JEV, a hosted decision model via OpenRouter, picks tools and elements. Zero data retention requested on every call, text first, screenshots only when unsure, local fallback.

// Where Hercules sits //

Into Your Browser, Out To Your Pipeline

Runs from the CLI, the local tester UI (hercules serve + hercules ui), or your coding agent over MCP. Built on LangGraph run and step graphs, with Chromium, Chrome, Edge, Firefox and WebKit.

// How the options compare //

Scripts, Cloud Agents, Or Hercules

Selector scriptsTypical cloud AI agentsHercules 2.0
AuthoringCode + locatorsPlain languagePlain language, JSON or Gherkin
Survives UI changesBreaks on moved selectorsUsuallyYes, elements chosen per run
Runs on your hardwareYesNoYes, from 16 GB RAM
Data leaving your machineNonePages & screenshotsYour egress policy decides
VerdictsHand-coded assertsModel judgmentPlan + assertion ledger, unverified fails
Cost per runEngineer timePer-run / per-token$0 on a local model
Exit to plain coden/aRarelyPlaywright Test / pytest export
LicenseVariesProprietaryAGPL-3.0

See It Run On Your Own App

One line installs the hercules command, sets up browsers, connects a model and your coding agent, asking before every change.

Get Started In 5 Minutes
// Get started //

From Zero To A Passing Test In Minutes

macOS or Linux, Python 3.12 (3.11–3.15 work), and a model endpoint. For a fully local setup, 16 GB of memory.

Terminal
uvx testzeus-hercules
# no uv? → pipx run testzeus-hercules
# until v2 is on PyPI:
uvx --from git+https://github.com/test-zeus-ai/testzeus-hercules.git testzeus-hercules
.hercules/cases/sign-in.json
{
  "id": "sign-in",
  "title": "User signs in",
  "environment": { "base_url": "http://localhost:3000" },
  "test_data": {
    "email": "demo@example.com",
    "password": { "secret": "APP_TEST_PASSWORD" }
  },
  "steps": [
    { "action": "Open \"/login\"" },
    { "action": "Fill \"{{email}}\" in \"Email\"" },
    { "action": "Fill \"{{password}}\" in \"Password\"" },
    { "action": "Click the \"Sign in\" button",
      "expected": "I should see \"Welcome back\"" }
  ]
}
Run it
export APP_TEST_PASSWORD=...
hercules plan .hercules/cases/sign-in.json
hercules run  .hercules/cases/sign-in.json
Connect your coding agent
hercules init --agent claude
# or codex · cursor · copilot · gemini · generic
// See it in action //

14 Features, 14 Short Videos

Each has a spoken walkthrough, recorded against the demo shop that ships in the repo, so you can reproduce every one on your machine.

// Hercules 2.0, answered //

Frequently Asked Questions

Is Hercules really free and open source?

Yes. Hercules is licensed under AGPL-3.0. The source, docs, demo shop and benchmark scenarios are all on GitHub.

Do I need a GPU or a paid API key?

No. On macOS or Linux with 16 GB of memory, Hercules runs Gemma 4 on a local server such as Ollama or LM Studio; 32 GB is the recommended tier. An OpenRouter key is optional and only switches on hybrid mode.

What is JEV?

JEV is a hosted decision model served through OpenRouter. In hybrid mode it answers the typed decision questions (which tool, which element, did the step work) while your local model reads the steps. Zero data retention is requested on every call; if JEV can't answer, the local model does.

How is this different from Playwright?

Hercules runs on Playwright, but you write steps in plain language instead of selectors. When a run passes, you can export it as a regular Playwright Test or pytest-playwright file.

How is it different from browser-use-style agents?

Hercules is a QA engine, not a general browsing agent: every run has a plan with success criteria, every expected outcome is recorded, and a run only passes when nothing stayed unverified. You also get CI exit codes, JUnit, evidence folders and a tester UI.

Does any of my data leave my machine?

Only what your egress policy allows. With local, nothing leaves and telemetry is off. Models see secret placeholders, never values, and values are masked in every evidence file.

Which coding agents does it work with?

Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI, over MCP. Run hercules init --agent <name> once and the agent gets the Hercules tools.

What isn't in v2 yet?

Running a whole folder or suite in one command, and scheduled runs with regression alerts. For now, loop over cases or queue them on the daemon, and schedule that loop in CI.

// Start testing //

Stop Paying Per Click To Test Your Own App

Star the repo, run it on your app tonight, and tell us what breaks.

$uvx testzeus-hercules

Need test management, creation, execution and reporting in the cloud? See TestZeus Pro →