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.
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.
uvx testzeus-hercules
Hercules picks a hardware tier from your memory · Gemma 4 on Ollama, LM Studio, llama.cpp, vLLM or MLX · macOS & Linux
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.
Scripted suites break when an ID, class or layout changes. Someone has to babysit locators instead of testing the product.
A model said "looks good". Without a plan, recorded assertions and evidence per step, a green run is a guess you can't audit.
Cloud-only agents send page content and screenshots off your machine. Regulated and air-gapped teams can't use them at all.
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.
.hercules/runs/<run_id>/.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.
local: nothing leaves, telemetry offClaude 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 claudeTurn 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 --checkThe local model reads the steps and makes every decision (or a local Clef server decides). Pair with --egress local for air-gapped teams.
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.
.featurejunit.xml, run.jsonRuns 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.
| Selector scripts | Typical cloud AI agents | Hercules 2.0 | |
|---|---|---|---|
| Authoring | Code + locators | Plain language | Plain language, JSON or Gherkin |
| Survives UI changes | Breaks on moved selectors | Usually | Yes, elements chosen per run |
| Runs on your hardware | Yes | No | Yes, from 16 GB RAM |
| Data leaving your machine | None | Pages & screenshots | Your egress policy decides |
| Verdicts | Hand-coded asserts | Model judgment | Plan + assertion ledger, unverified fails |
| Cost per run | Engineer time | Per-run / per-token | $0 on a local model |
| Exit to plain code | n/a | Rarely | Playwright Test / pytest export |
| License | Varies | Proprietary | AGPL-3.0 |
One line installs the hercules command, sets up browsers, connects a model and your coding agent, asking before every change.
macOS or Linux, Python 3.12 (3.11–3.15 work), and a model endpoint. For a fully local setup, 16 GB of memory.
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
ollama pull gemma4:26b-a4b-it-qat
OLLAMA_CONTEXT_LENGTH=32768 ollama serve # 32 GB machine
hercules setup # model server, egress policy, telemetry
hercules doctor # measures what the endpoint supports
docker build -t hercules . # in the clone
docker run -d --name hercules --shm-size=1g \
-p 127.0.0.1:7373:7373 -v "$PWD:/work" hercules
docker logs hercules # the one-time sign-in link
hercules import v1 path/to/v1-project --dry-run
hercules import v1 path/to/v1-project
hercules run .hercules/cases/<id>.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\"" }
]
}
export APP_TEST_PASSWORD=...
hercules plan .hercules/cases/sign-in.json
hercules run .hercules/cases/sign-in.json
hercules init --agent claude
# or codex · cursor · copilot · gemini · generic
Each has a spoken walkthrough, recorded against the demo shop that ships in the repo, so you can reproduce every one on your machine.
Yes. Hercules is licensed under AGPL-3.0. The source, docs, demo shop and benchmark scenarios are all on GitHub.
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.
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.
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.
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.
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.
Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI, over MCP. Run hercules init --agent <name> once and the agent gets the Hercules tools.
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.
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 →