Offline WCAG accessibility audit agent

What it does

• Audits HTML files or inline snippets with Python standard-library parsing.
• Finds missing image alt text, unlabeled controls, empty links/buttons, heading-order skips, duplicate IDs, missing document title/language, positive tabindex, timed refresh, and missing viewport metadata.
• Produces JSON reports for CI and text summaries for developers.
• Uses a local LLM CLI only for remediation planning when one is connected.
• Falls back to deterministic remediation advice with no credentials required.

Quick start

python agent.py audit --html '<img src="hero.png">'
python agent.py scan --dir ./dist --format text
python agent.py remediate --file ./dist/index.html --deterministic

Install on a Debian or Ubuntu VM

sudo bash install.sh

Set A11Y_TARGETS to a comma-separated list of globs when running the service. For example: A11Y_TARGETS="/srv/site/**/*.html,/srv/docs/**/*.html".

LLM mode

Install and log in to one supported local CLI, then run remediate without --deterministic. The agent loads PROMPTS.md and asks for a JSON remediation plan. If the CLI is absent or unavailable, deterministic mode is used instead.

Packtest audit mode (deterministic_audit)

The packtest bench scores the deterministic core directly (no LLM). The audit report it consumes is the JSON object returned by audit_html / audit --format json, with the exact schema below — distinct from the internal remediate plan:

{
  "ok": false,
  "mode": "deterministic_audit",
  "elements_scanned": 13,
  "summary": {"critical": 2, "serious": 4, "moderate": 5, "total": 11, "text": "..."},
  "violations": [
    {"rule": "img-alt", "severity": "critical", "wcag": "1.1.1",
     "line": 7, "message": "hero.jpg", "fix": "Add alt text ..."}
  ]
}

• ok is a strict boolean: true only when the ruleset found zero violations. The --fail-on gate controls the CLI exit code and never rewrites ok.
• mode is always the exact string deterministic_audit in this report.
• elements_scanned counts every parsed element (including head and meta).
• Head-anchored rules (doc-title, viewport-meta) are reported at line: 1.
• Rule identifiers, severities, and WCAG references follow the canonical table in SPEC.md and are emitted verbatim so bucket_contains scoring matches.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.