allycat

A source-first accessibility scanner — catch WCAG violations in your editor, on every save, or as a CI gate that blocks inaccessible code from shipping.

Most accessibility violations reach production because the tools that catch them need a deployed app — too late, and disconnected from the code that caused them. AllyCat closes that gap.

Built for how developers actually work: a CLI that scans your source files, jumps to the exact line with a clickable link, and feeds your AI agent ready-made fix prompts that save tokens. Runs in pre-commit hooks and CI — no deployed app required.

Supports: JSX/TSX, Vue, Angular, HTML • RTL (experimental) • Contrast checking

Table of Contents

• Features
• Why AllyCat
• Quick Start
• Installation
• Commands
• Configuration
• Supported File Types
• Output Formats
• CI/CD Integration
• More
• License

Features

• ⚡ Lightning-fast JSDOM scans (~1s/file, no browser needed)
• 🔍 Full browser scans with real contrast checking via Playwright
• 🔤 RTL support (experimental) — opt-in for Hebrew, Arabic, Persian interfaces
• 📍 Exact line numbers with clickable VS Code links
• 📋 AI-ready fix prompts — copy-paste into your AI agent (no API key, no data sent)
• 🤖 One-command fixes — allycat fix hands your last scan to Claude Code
• ⚙️ Watch mode with NEW/FIXED delta detection
• 🛠️ CI-ready — baselines, exit codes, and --changed git scoping
• 📊 Terminal, JSON, and self-contained HTML outputs

Why AllyCat

Most accessibility tools need a deployed app. AllyCat scans your source files directly — JSX, Vue, Angular, HTML — giving you exact line numbers and AI-ready fix prompts before anything ships.

Quick Start

# 1. Install
npm install -g allycat

# 2. Initialize
allycat init

# 3. Scan
allycat scan

Full scans (contrast checking) require Chromium — install once with npx playwright install chromium, then run allycat scan --full.

See all options with allycat scan --help.

Scan violations with exact line numbers → save a baseline → catch only new violations with --fail-on-new

Installation

# Global — for personal use
npm install -g allycat

# Per-project — recommended for teams and CI/CD (version-pinned per project)
npm install --save-dev allycat

For full scans (contrast checking):

npx playwright install chromium

Requirements: Node.js ≥ 20

Commands

allycat init

Interactive setup wizard. Creates allycat.config.json in your project root.

allycat init

Prompts for:

• Accessibility standard (WCAG 2.1 AA, WCAG 2.2 AA, WCAG AAA)
• RTL support (experimental, opt-in)
• Default scan mode (quick or full)
• AI-ready fix prompts (enabled/disabled)
• AI agent preference — Claude, Cursor, ChatGPT, Gemini, Copilot, Other / Skip (shown when AI is enabled)
• Report delivery — Auto-open in browser / Save and print path / Ask each time / Never generate (shown when AI is enabled)
• Concurrency override (optional advanced setting)

No framework selection needed — the scanner automatically detects .html, .jsx, .tsx, .vue, and Angular template files.

allycat scan [target]

Scan files for accessibility violations.

allycat scan                        # entire project
allycat scan ./src                  # specific directory
allycat scan ./src/pages/Home.tsx   # specific file

Scan Mode

allycat scan            # quick scan (default)
allycat scan --full     # full scan with contrast checking
allycat scan --summary  # counts only — no per-violation details

Watch & Scope

allycat scan --watch              # re-scans on every save
allycat scan --watch --existing   # include pre-existing violations on startup
allycat scan --watch --summary    # watch mode with counts only
allycat scan --changed            # git-changed files only (great for CI / PR pipelines)
allycat scan --changed ./src      # scoped to a directory

# After each save, watch mode shows a delta:
#   [NEW]   — violation appeared since the last scan
#   [FIXED] — violation was present before and is now resolved
#   (no label) — violation is unchanged

Path Filtering

allycat scan --exclude tests                          # skip the tests folder
allycat scan --exclude tests --exclude src/generated  # skip multiple paths
allycat scan --exclude "**/*.stories.*"               # skip all Storybook stories (glob)
allycat scan --watch --exclude tests                  # exclusion applies on every rescan too
allycat scan scripts --exclude test.html              # scans scripts/ — auto-resolves to scripts/test.html
allycat scan src/components --exclude fixtures        # auto-resolves to src/components/fixtures (entire folder)
allycat scan src/test --exclude __mocks__             # auto-resolves to src/test/__mocks__

Stacks on top of the built-in ignores (node_modules/, dist/, build/, allycat-report.html). Works in normal scan, watch, and --changed modes.

CI & Gates

allycat scan --ci                                     # CI preset — compact output + critical gate
allycat scan --fail-on-critical --json-file report    # block on critical, save report
allycat scan --fail-on-any                            # strictest gate — block on any violation
allycat scan --save-baseline                          # snapshot today's violations
allycat scan --fail-on-new                            # only fail on violations not in baseline
allycat scan --json-file                              # auto-named: allycat-report-2026-06-02-143052.json
allycat scan --json-file ci-report                    # custom name: ci-report.json

→ See CI/CD Integration Guide for exit code reference, baseline workflow, pre-commit hooks, and full pipeline examples.

Output

allycat scan -o json                   # JSON to terminal (pipe-friendly)
allycat scan --no-snippet --no-help    # cleaner terminal output
allycat scan --summary-style compact   # single-line summary

Full reference: allycat scan --help

allycat help [topic]

allycat help           # List all topics
allycat help faq       # Common questions and answers
allycat help examples  # Real-world usage examples
allycat help ci        # CI/CD integration guide
allycat help standards # Standards explained (WCAG AA vs AAA)

Command-specific help:

allycat --help        # All commands overview
allycat init --help   # Init command details
allycat scan --help   # Scan command with all options

allycat report

Opens the last generated HTML accessibility report (allycat-report.html) in your browser.

allycat report

Run allycat scan first. Prints a message and exits if no report file is found.

allycat fix

Opens Claude Code in a new terminal and hands it every violation from your last scan to fix.

allycat scan      # 1. Find the violations
allycat fix       # 2. Claude Code fixes them

• Requires Claude Code. If it isn't installed, fix tells you where to get it.
• Uses your last scan. fix doesn't scan again, so run allycat scan in the same folder first.
• Warns about stale results. If files changed since the scan, fix tells you and still continues.
• Never gets stuck. If a new terminal can't be opened, fix prints the command to run yourself.

fix runs Claude Code with your own account and settings. Review its changes before committing, then run allycat scan again to confirm.

allycat feedback

Opens GitHub Issues in your browser to report a bug or request a feature.

allycat feedback

allycat repo

Opens the AllyCat GitHub repository in your browser.

allycat repo

allycat update

Check for updates and view release notes.

allycat update

Configuration

Run allycat init to create allycat.config.json in your project root. Valid standards are wcag-aa (default), wcag-22-aa, and wcag-aaa.

→ See Configuration Reference for all fields, valid values, and manual editing details.

.allycatignore

Create a .allycatignore file in your project root to permanently exclude paths from every scan. One glob pattern per line, # for comments:

# Generated files — do not scan
src/generated/**
public/vendor/**

# Legacy code pending refactor
src/legacy/**/*.html

Loaded automatically on every scan — no flag needed. Commit the file to share exclusions with your team. .allycatignore always wins: even if a path is explicitly targeted, this file blocks it. Use --exclude for per-run exclusions; both apply simultaneously. To bypass .allycatignore for a single run without editing the file, use --no-ignore.

Supported File Types

Ignores node_modules/, dist/, build/, and allycat-report.html by default. Use --exclude for per-run exclusions or .allycatignore for project-wide permanent exclusions.

Output Formats

• Terminal — Color-coded, grouped by file
• JSON — For CI/scripts:

  allycat scan -o json             # print to terminal
  allycat scan --json-file report  # save to report.json
  

• HTML Report — Rich AI fix prompts (auto-opens when enabled)

CI/CD Integration

AllyCat is built for pipelines:

• Exit gates — fail on critical, serious, or any violations (--fail-on-critical, --fail-on-serious, --fail-on-any)
• Baselines — adopt a gate without fixing pre-existing issues (--save-baseline + --fail-on-new); resilient to file renames and unrelated code changes, so existing violations stay suppressed
• PR scoping — scan only git-changed files (--changed)
• CI preset — compact output + critical gate in one flag (--ci)
• JSON export — machine-readable reports for artifact storage (--json-file)

GitHub Actions example:

- name: Accessibility Scan
  run: allycat scan --ci --json-file allycat-report

→ See CI/CD Integration Guide for GitHub Actions, GitLab CI, Jenkins, and advanced baseline workflows.

More

License

MIT © 2026 Dotan Siman Tov