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.
Swipe sideways to see the whole screen.
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">
- now:
- 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.
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
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
README: Quick start
First, open a terminal, the window where you type commands:
- Windows: open Start, type
Terminal(on Windows 10,PowerShell) and pressEnter. - macOS: press
Cmd+Space, typeTerminaland pressEnter. - Linux: press
Ctrl+Alt+T(on Ubuntu and many others), or find Terminal in your app menu.
The recommended way to install is uv (opens in a new tab), a fast installer for Python tools. It brings its own Python, so you don't need to install Python first, and it puts the magnacoda command on your PATH, with no virtual environment to set up or activate.
Install uv (once), then open a new terminal window so it finds the uv command:
- Linux and macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh(on macOS,brew install uvworks too). - Windows:
winget install astral-sh.uv. If you don't have winget (some older Windows 10 installations), uv's own installer does the same:powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex".
Install magnacoda, then run your first scan:
uv tool install magnacoda
magnacoda setup # one-time: downloads the Chromium browser (~300 MB), and shows how the AI tiers will run
magnacoda wizard # a few questions, then it runs the scan for you (the first setup offers to start it)
magnacoda scan example.com # or scan a page straight away; https:// is filled in for you (see URL rules)
Next time, open a terminal and type magnacoda to start the shell, or magnacoda wizard to go straight to the guided wizard. For more, including what to do if your terminal doesn't find magnacoda, see Starting magnacoda (from the magnacoda shell, type docs starting).
To uninstall, type magnacoda uninstall. That one command removes magnacoda and its shortcuts, whichever way you installed it. It asks first, and you choose whether your settings, Chromium and saved scans go too. For more, see Uninstalling.
With pipx instead
If you already use pipx (opens in a new tab), it works just as well. It uses a Python already on your computer, which must be 3.11 or newer (Ubuntu 22.04's is 3.10, too old; uv avoids this). Get pipx from your system's own installer rather than with pip, which recent Linux versions block:
- Ubuntu and Debian:
sudo apt install pipx - Fedora:
sudo dnf install pipx - macOS:
brew install pipx, with Homebrew (opens in a new tab) - Windows: install Python first, from python.org (opens in a new tab) or with
winget install Python.Python.3.12, thenpy -m pip install --user pipx. Avoid the Microsoft Store version of Python, because it quietly redirects some of the folders magnacoda uses and makes its settings and browser hard to find.
Then run pipx ensurepath (on Windows, py -m pipx ensurepath), open a new terminal window, and install:
pipx install magnacoda
magnacoda setup
Installing from a downloaded copy of the code (a zip or a clone, for example to try a version that isn't released yet):
Where to put it: a short folder outside OneDrive, such as
C:\dev\magnacoda.- OneDrive syncs Documents and Desktop, and syncing can lock files while the install runs.
- Windows 10 limits most paths to 260 characters, and the install creates deep folders, so a short starting point helps.
- Avoid Program Files, which needs administrator rights. Creating
C:\devdoesn't.
Check the folder: the path you give pipx or uv must be the folder that directly contains
pyproject.toml, such asC:\dev\magnacoda. Unzipping often creates a doubled folder,C:\dev\magnacoda\magnacoda; if so, move everything from the inner folder up into the outer one, then delete the empty inner folder.Install it by giving the folder's full path. It doesn't matter which folder your terminal is in, since the installer goes by the path you give. Use one of these two, depending on whether you use uv or pipx (install that first, as shown above):
- With uv:
uv tool install C:\dev\magnacoda - With pipx:
pipx install C:\dev\magnacoda
Then, either way, run
magnacoda setuponce to download the browser.An add-on you've downloaded the same way goes into the same install:
- With uv:
uv tool install C:\dev\magnacoda --with C:\dev\example-addon(the install command again, with the add-on added; uv rebuilds the install to include it) - With pipx:
pipx inject magnacoda C:\dev\example-addon
To learn what add-ons are and how they show up in magnacoda, type
help add-ons. To write your own, see Writing an add-on.- With uv:
Keep the folder if you may want to reinstall from it later. The installer copies everything it needs, so magnacoda doesn't run from it.
If Windows says a command is not recognized:
magnacoda,pipxoruv: open a new terminal window. A newly installed command is only found in windows opened after it was installed (for pipx, afterpy -m pipx ensurepath).pipx, still: check it's installed (py -m pip install --user pipx). You can also run it through Python, which needs no PATH at all:py -m pipx install C:\dev\magnacoda.py: usepythoninstead (python -m pip install --user pipx, and so on).pycomes with Python from python.org; if it's missing, your Python may be the Microsoft Store version (see above).
To update later, run magnacoda update (see Updates and news).