Achilles

Point your coding agent at a web app. Get back a Playwright suite you own.

Achilles is a QA team that lives inside your agent. Hand it a URL and it maps the app, writes the tests, hunts for bugs, and has every piece of work checked by a reviewer that did not write it. What lands in your repo is plain Playwright: specs that run with npx playwright test, no agent required.

It also takes the jobs nobody wants: a red suite after a refactor, a ticket that needs proof before it closes, a flaky test that fails one run in ten.

you    /achilles onboard this project; the app runs at http://localhost:3000, login is in .env
       RUNNING  run 2026-11-01-a7c3   (you keep working, progress shows in the status line)

       ... inspector maps 9 journeys, author writes them, reviewer re-runs every one ...

       DONE  41 specs across 9 journeys, all green on 3 consecutive runs
             2 app bugs reported with reproductions (tests/e2e/docs/adversarial-findings.md)
             secrets moved to .env, committed in 6 commits

An illustration of the flow; real counts depend on your app.

Quick start

You need Node 20+, a web app with a reachable URL, and Claude Code 2.1.287+ (or pi).

npm i -D @civitas-cerebrum/achilles   # registers the Claude Code plugin in place, fetches Chromium

Restart Claude Code, then ask:

/achilles onboard this project; the app runs at http://localhost:3000

That's it. On npm 11+, if npm lists Achilles under blocked install scripts, run npm install-scripts approve @civitas-cerebrum/achilles and install again. Other ways to install are below.

What you can ask for

Specialist skills join in when the work calls for them: API contract tests, database assertions, k6 performance tests, red-teaming AI features, inert test-attribute selectors, test-data lifecycle, bug reports, and a summary deck for stakeholders.

What lands in your repo

Ordinary Playwright specs on @civitas-cerebrum/element-interactions, with selectors kept in one page repository instead of scattered through the tests:

// tests/e2e/checkout.spec.ts
import { test } from '../fixtures/base';

test('a signed-in shopper can check out a single item', async ({ steps }) => {
  await steps.navigateTo('/products/veggie-wrap');
  await steps.click('addToCart', 'ProductPage');
  await steps.click('checkoutButton', 'CartPage');
  await steps.verifyText('orderStatus', 'ConfirmationPage', 'Order placed');
});

// tests/e2e/page-repository.json
{ "pages": [{ "name": "CartPage", "elements": [
  { "elementName": "checkoutButton", "selector": { "role": "button", "name": "Checkout" } }
]}]}

The tests run in CI like any other suite. Achilles is only needed to write and repair them.

How it works

your session ──/achilles──▶ orchestrator ──brief──▶ inspector     drives the live app, gathers evidence
     ▲                         │   ▲                author        writes specs and the page repository
     │                         │   └──report────── reviewer      fresh instance, verifies, never edits
     │                         │                    reproducer    decides whether a suspected defect is a bug
     └────── one verdict ──────┘                    doc-writer    maps, reports, decks

• Your session stays yours. The work runs in a separate orchestrator agent in the background. You get RUNNING and a run id at once, and one hand-back at the end: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT or BLOCKED.
• Nobody marks their own homework. Every unit of work is checked by a fresh reviewer before the run moves on. An author cannot approve, and a reviewer cannot edit.
• No questions mid-run. If Achilles needs something from you, it commits what it has, writes a resume file and asks everything at once. Answer in the chat and it picks up where it stopped; /achilles resume <run-id> works after a crash too.
• Bugs are reported, not worked around. A suspected app bug never becomes the expected result: the test keeps the correct assertion, is tagged @known-defect and points at the finding, with its evidence.
• The finder does not confirm. Before a suspected defect becomes a sentinel or a ticket, a fresh reproducer decides from the criteria, the live app and the source whether it is a bug, real only in the source, a spec question or intended. On Claude Code a defect filing or a sign-off without that verdict is refused.
• Guardrails, not handcuffs. On Claude Code eight hooks watch the Achilles agents. They advise by default and block only what can't be undone: force pushes, rm -rf outside the project, bypassed commit checks, credentials in committed files, sign-off without a reviewer receipt.

The full contract is in skills/achilles-orchestrator/SKILL.md, and the design thinking in Agentic Shift-Left.

Tools that come with it

There's also a Playwright reporter that remembers. It keeps a local history of every test, so a failure shows up as failed 6 of last 10 runs, and it copies each failing attempt's evidence. It never fails a run.

reporter: [['list'], ['html', { open: 'never' }], ['@civitas-cerebrum/achilles/reporter']],

History lives in .achilles/history/tests.ndjson and per-attempt evidence in .achilles/runs/<runId>/. Set ACHILLES_REPORTER=off to disable it.

Install

Restart Claude Code after installing. To uninstall, run claude plugin uninstall achilles or delete the achilles entries postinstall added to the settings file.

Run the suite in CI

The scaffold writes playwright.config.ts, the specs, fixtures, a setup file and a test:repair script, but no CI workflow, because CI doesn't need Achilles. A starting point:

# .github/workflows/e2e.yml
name: e2e
on: [pull_request]
jobs:
  e2e:
    runs-on: ubuntu-latest
    env:
      ACHILLES_SKIP_CLAUDE_REGISTRATION: "1"
      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --reporter=junit
        env:
          # the secrets sweep moved credentials into .env (gitignored); pass them here
          E2E_USER: ${{ secrets.E2E_USER }}

Rename the variables to match your .env. The commands are Playwright's own; this recipe hasn't been run against an onboarded project in this release.

Under the hood

What Achilles is not

• Not a hosted service. No runner, no dashboard; everything runs on your machine or your CI.
• Not native mobile. "Mobile variants" are viewport emulation in Playwright.
• Not runtime self-healing. Repair happens in an agent session or through achilles-self-repair; a CI run never asks a model to retry a step.
• Not enforced outside Claude Code. On pi the skills state the same rules; keeping them is the operator's job.
• Not benchmarked yet. Detection rate, cost and duration haven't been measured and published. Onboarding dispatches many subagents and uses a large share of a plan's usage window.

Upgrading from 0.1.7 or a 0.2.0 branch install

Earlier versions copied hooks, skills and agents into .claude/. 0.1.8 copies nothing, and the old copies keep running until you remove them:

1. With the old package still installed, run npx achilles-uninstall --project (and --global if you used -g). 0.1.x had no uninstaller; skip to step 2.
2. Delete what's left by hand, and remove the hooks entries in .claude/settings.json that point into .claude/hooks/.
3. Install 0.1.8, restart Claude Code, and drop ACHILLES_PROTOCOL, KERNEL_MANDATE, CIVITAS_SKIP_HOOK_INSTALL and CIVITAS_SKIP_JQ_INSTALL from shells and CI.
4. Replace the old slash commands (/onboarding, /coverage-expansion, /test-repair, …) with /achilles <task>.

The exact file list for step 2 is in the CHANGELOG.

Contributing

See CONTRIBUTING.md for the methodology/adapter split, commit conventions (no AI attribution trailers), the doc lint and the PR checklist. npm test runs every suite: schemas, doc lint, CLIs, reporter and adapter.

License

MIT