Scan for web accessibility issues.
Learn to fix them.

magnacoda

Welcome

magnacoda™ is an accessibility scanner for WCAG, the Web Content Accessibility Guidelines, that you run from your terminal. It's built for developers and content managers who want to understand and fix accessibility problems, not just list them.

These are screens from magnacoda, from a scan of a sample page.

Menu

magnacoda » menu

magnacoda accessibility scanner - type a command, or exit to leave.
Commands: wizard · scan · help · setup · review · update · about · menu
Add-on commands: favorites

    Tip: Type menu any time to see the commands, or clear
    for a fresh page.

magnacoda »

The menu, from magnacoda in a terminal.

Scan

magnacoda » scan https://unrealbakeshop.example/

Ctrl+C or q cancels at any time.

The defaults: WCAG 2.2 AA, a desktop screen, light and dark mode, no AI.
You can type: options (such as --option), defaults, help. Enter cancels.
Options » defaults

 Scanning https://unrealbakeshop.example/ - 5 s so far

A scan of the sample page, from magnacoda in a terminal.

Results

magnacoda » scan https://unrealbakeshop.example/

Ctrl+C or q cancels at any time.

The defaults: WCAG 2.2 AA, a desktop screen, light and dark mode, no AI.
You can type: options (such as --option), defaults, help. Enter cancels.
Options » defaults


Tested on desktop, in light mode (the page looks the same in dark mode).
Found 12 problems on 12 elements (2 critical, 9 serious, 1 moderate), and
49 items to check.
The scan took 19 s.
Saved in ~/Documents/magnacoda-scans/unrealbakeshop.example_20261119-105414.

Type review to see them in your browser, and recheck once
you've fixed some.

magnacoda »

The scan's results, from magnacoda in a terminal.

Review

9. input ("Your email")

  • Fix 1.3.5 Identify Input Purpose (opens in a new tab) (AA) - It looks like it asks for the visitor's own email address, but has no autocomplete value, so browsers can't fill it in and assistive tools can't show what it's for (moderate; rule magnacoda/missing-autocomplete)
    • now: <input type="email" placeholder="Your email">
    • fix: Add autocomplete="email", if the field asks for the visitor's own details (for someone else's, such as a gift's recipient, leave it out).
    • e.g. <input type="email" placeholder="Your email" autocomplete="email">
  • Checked: tick when you've looked at everything below that needs a person
  • Check 3.3.1 Error Identification (opens in a new tab) (A) - Submit invalid or empty input: errors must be shown in text and identify the field in error.
  • Check 3.3.3 Error Suggestion (opens in a new tab) (AA) - When an input error is detected and a fix is known, the message should suggest it.
  • Check 4.1.3 Status Messages (opens in a new tab) (AA) - Status messages (success, errors, result counts) must be announced via role=status/alert or live regions without moving focus.

One finding from the scan of the sample page, on the review page in your browser.

See the full review

Help

magnacoda - Help

magnacoda is a WCAG 2 accessibility scanner for developers and content
managers comfortable in a terminal. It explains what it finds and how to fix
it, so you can act on the results right away and learn as you go.

- Open a terminal and run magnacoda with no arguments to start an
  interactive shell. Let the wizard ask a few plain-language questions and
  build the scan for you. To learn how to open a terminal on your computer,
  type docs starting.
- Or scan a page directly from the command line with magnacoda scan URL
  [OPTIONS]. The URL can be short, such as example.com or localhost:3000:
  magnacoda fills in the rest.
- To use the AI tiers you can provide your own Anthropic API key (setup
  can save one for you), or use Claude Code if it is installed and logged
  into your Claude subscription.
- AI works with magnacoda both ways: your AI coding agent can run it, and
  it can use AI itself. To see both in one round of work on a page, type

1/14 overview | g go | o open | c colors | ← back | → next | Esc quit
Scroll: ↑ ↓ | lines 1-16 of 25

The help, from magnacoda in a terminal. You can read all of it in Read the docs.

Setup

magnacoda » setup

Ctrl+C or q cancels at any time.
Chromium is already installed.

A shortcut opens magnacoda in a terminal window, from your app menu or
desktop.
Add a magnacoda shortcut to (menu, desktop, both, skip) [skip] »


AI tiers (optional; magnacoda works fine without them):

Claude Code is installed, so the AI tiers can use your Claude plan (such as
Pro or Max) instead of an Anthropic API key, which the API bills per use.
Use your Claude plan for the AI tiers? [Y/n] »

Setup, from magnacoda in a terminal.

magnacoda docs

Manual: How do I use it with CI, scripts and AI agents?

The shell and the wizard are for people. For everything else, magnacoda is a single command. Every choice is an option on the command line, it never stops to ask a question when nobody is there to answer, and its exit code says how the scan went. That's what lets it run in a CI pipeline, from a script, or from an AI coding agent.

magnacoda scan https://staging.example.com --fail-on serious --scans-dir magnacoda-scans -o accessibility.json
  • Every scan is saved in its own folder: the checklist, results.json and screenshots of the page's images. --scans-dir magnacoda-scans puts them in the project folder instead of the machine's Documents. Keep that folder as a build artifact to look at a failed run later (copy it to your computer and type review FOLDER).
  • -o FILE also writes the results to a file name of your choosing, since each scan folder is named after the site and the time; an existing file is replaced. -o - prints the JSON instead, for another program to read (the short summary goes to standard error, so it doesn't mix in).
  • --fail-on sets which problems fail the run (critical, serious, the default, moderate, minor, or none). The exit codes: 0 when nothing at or above --fail-on was found, 1 when something was, and 2 when the scan couldn't finish, such as a page that couldn't be loaded (it always says why: "Error: ..."). When the output isn't a terminal, as in a script or CI log, a last line also explains the code, such as "Exit code 1: 2 problems at or above serious." An unexpected error also exits with 2 and prints one short message; errors shows the details, or run the scan again with -v. --fail-on none always exits 0 after a scan. Ctrl+C stops a scan at any point, saves nothing and exits with 130; in the shell it says "Cancelled." and returns to the prompt.
  • --show-findings prints the full findings into the log, besides the short summary.
  • --quick leaves out the slowest tests that use the page, for about 10 seconds a scan.
  • Nothing else happens: no question is asked, the daily check for updates and news never runs in CI or when output isn't a terminal, and nothing is sent to an AI unless you add --ai (then also -y, to accept the consent question in advance, and an ANTHROPIC_API_KEY).

Every option is in Scan options and Advanced scan options, and listed briefly in help scan and help advanced. An option magnacoda doesn't have gets a one-line error, and the run exits with code 2.

GitLab CI

accessibility:
  stage: test
  image: python:3.12
  script:
    - pip install magnacoda
    - python -m playwright install --with-deps chromium
    - magnacoda scan https://staging.example.com --fail-on serious --scans-dir magnacoda-scans -o accessibility.json
  artifacts:
    when: always
    paths:
      - magnacoda-scans/
      - accessibility.json

GitHub Actions

name: Accessibility
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"
      - run: pip install magnacoda
      - run: python -m playwright install --with-deps chromium
      - run: magnacoda scan https://staging.example.com --fail-on serious --scans-dir magnacoda-scans -o accessibility.json
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: accessibility
          path: |
            magnacoda-scans/
            accessibility.json

Notes for both:

  • The browser: python -m playwright install --with-deps chromium installs Chromium and the system libraries it needs on Linux. That needs administrator rights, which CI jobs have (Playwright uses sudo when the job doesn't run as root). On your own computer, magnacoda setup downloads the browser instead.
  • Scanning the site the job builds: start it in the background, then scan its local address, such as npx serve dist -l 8080 & and then magnacoda scan localhost:8080 --fail-on serious.
  • Several pages: one magnacoda line per page, each with --scans-dir magnacoda-scans; each gets its own folder there.
  • Pages behind a login: see Pages behind a login; keep the values in your CI system's secret variables.

Scripts

A scan from a script works the same way. For example, a quick look at a few pages, carrying on whatever each finds:

for page in / /about /contact; do
  magnacoda scan "https://example.com$page" --quick --fail-on none
done

Each scan is saved, so review then lists them all, and recheck tests the fixes in any of them again.

From an AI coding agent

AI coding agents (such as Claude Code, Cursor or GitHub Copilot's agent) run command-line tools to check their own work. An agent that has just changed a page can scan it and read what was found:

magnacoda scan localhost:3000 --quick --fail-on none -o -

This prints the results as JSON. The parts an agent needs most:

  • findings: each problem, with rule_id, wcag_criteria, severity, selector, html_snippet, a suggested fix (its summary), and, for problems a style causes, css: the rule, file and line that set it.
  • checklist: every WCAG criterion in scope, with its status (failed, passed, still to check by a person, and so on).
  • needs_review: what axe-core couldn't decide.

The saved checklist.md is just as useful. It's written for people, so an agent can read it too, and it says what still needs a person. To have an agent check its work as a habit, add a line such as this to its instructions file (CLAUDE.md, AGENTS.md or similar): After changing a page, run magnacoda scan localhost:3000 --quick --fail-on none -o - and fix what it finds.

For a whole round of work, with AI on both sides, see the next section.