Using CORA in an agent

A first prompt

Invoke the plugin’s fix skill, followed by what to check or fix:

Claude Code

/cora:fix the checkout form, report only

Codex

$cora:fix the checkout form, report only

The main agent dispatches CORA’s fixer with your request. The fixer scans the pages that render the checkout form, and reports what it finds without changing anything. The main agent then presents its result. With nothing after the command, the fixer scans the targets in your CORA config and fixes what it finds.

You can also ask in your own words, such as “check the accessibility of the sign-up page”. The main agent dispatches the fixer whenever you ask for a CORA scan. It does so too when you ask to scan, check, audit or fix the accessibility of your app, a page or a component.

Workflows

Fix a page or a component

Name the page, the component or the files, such as /cora:fix the settings page. The fixer scans them, fixes what it can, and checks each fix in the browser. A change that needs your judgment comes back as a proposal, as does a fix of an issue your baseline accepts, unless your request asks for it, such as “fix the contrast issues on /pricing”: see The fixer. The fixer leaves every change uncommitted, for you to review.

Report only

Ask only what is wrong, or add “report only” to the request. The fixer scans and reports, and changes nothing.

Ask about CORA

Ask something no scan is needed for, such as which rules CORA runs, or what an issue it found means. The fixer answers, and scans and changes nothing.

The check after UI edits

When the main agent edits your app’s UI, such as a component or a stylesheet, it dispatches the fixer to check the pages that render it before it finishes. CORA’s hooks ask for it, as The fixer starts after UI edits describes. In Claude Code, by default, and in Codex the fixer runs in the background, so the main agent can finish, and your next request start, before the fixer returns (In Claude Code). Until it does, CORA asks the main agent to edit the files it handed the fixer only as your requests need, and to send the fixer each such edit; the hooks also pass on edits the main agent makes with its edit tools. Where the hooks do not run, the plugin’s cora:a11y-check-ui-edits skill has the agent ask for the same check. Where both ask, the agent dispatches the fixer once.

• The skill acts only in a project whose package.json lists @vispero/cora.
• With no fixer to dispatch, such as in Codex in a project without the fixer agent cora init sets up, the agent checks the pages itself with CORA’s tools.
• A subagent that cannot dispatch agents names the files it changed instead, for the agent that dispatched it.

Apply your decision on an issue

The fixer leaves some issues for you, such as what an image conveys. To have it apply your decision, such as the alt text to use, tell the main agent your decision.

Pausing and resuming CORA

To stop the fixer’s start after UI edits in a session, invoke the plugin’s pause skill. To have it start again, invoke its resume skill. The agent confirms each, and the hook confirms each with a warning too.

Claude Code

/cora:pause
/cora:resume

Codex

$cora:pause
$cora:resume

• The pause lasts until you resume CORA or the session ends. A new session starts unpaused.
• The pause stops the hooks’ asking and the cora:a11y-check-ui-edits skill’s check alike: the agent sees the pause and the resume in the conversation.
• After you resume, the hooks and the skill ask about UI edits made from then on, not those made while CORA was paused.
• The hooks still ask you before an edit of what decides what CORA reports. CORA’s tools still run in the fixer.
• Only you can pause or resume CORA. The agent cannot invoke either skill, and the hook acts only on a prompt you type.
• Without a CORA account, the hook takes neither the pause nor the resume. It warns why when no hook of the session has warned yet.

The fixer

CORA’s scans and fixes run in its fixer agent, so that scans and their findings stay out of your main conversation:

Agent	Fixer
Claude Code	the plugin’s cora:a11y-fixer, or cora-a11y-fixer where you set up the project agent
Codex	a11y_fixer, which cora init sets up in the project

The main agent dispatches it for your requests, as A first prompt describes, and after it edits your app’s UI. The fixer:

• scans the pages your request names, or those that render the files or components it names, in the states that show them;
• scans the targets in your CORA config when the request names none of those;
• starts your project’s own dev script when a page’s server does not answer, and stops it before it returns; where it cannot, it lists the page as not scanned;
• fixes what the page already settles, such as a field’s label from the text beside it;
• checks each fix in the browser with verify_fix, and hands an issue to you after three attempts without a fix;
• proposes, rather than makes, a change that needs a person’s judgment, such as what an image conveys, a control’s wording or a color;
• leaves the issues your baseline accepts unchanged, proposing a fix for each, unless your request asks for them: by an issue’s element, by the component or a file it is in, by its rule, or for the issues the baseline accepts;
• gives each proposal’s exact change, and what you must confirm;
• pins each fix it verified with a regression test in your project’s own test framework, where it can;
• names the fixes it left without a test, such as a fix of styles your project does not test;
• proposes a test where your project has no test framework;
• runs your project’s linter and type checker on what it changed;
• undoes an edit of its own by editing it back, never with a git command that discards changes, so your uncommitted work stays as it is;
• removes its scratch files, and stops the processes it starts, before it returns;
• leaves its changes uncommitted, and returns CORA’s summary, with the pages it scanned.

The summary names each page the fixer scanned only in part, or before the page settled, where CORA may have missed issues (Findings that differ between runs).

In Claude Code

• It runs on Claude’s Sonnet model at high effort, whatever model and effort level your session uses. CLAUDE_CODE_EFFORT_LEVEL, where you set it, sets its effort too.
• The main agent can name another model or effort for one dispatch, which Claude Code takes first. So instructions of yours that ask for a model on every dispatch run the fixer on that model. The fixer’s description asks the main agent to name no model unless you name one.
• It runs in the background, as Claude Code starts a subagent of the main conversation, and in a session in your terminal, VS Code or the desktop app, Claude cannot wait for it. So the main agent can finish its turn while the fixer works, and the fixer’s result arrives in a later turn. The hooks keep the fixer going while files it checked change, within the bounds The fixer starts after UI edits describes.
• To have the main agent wait for the fixer before it finishes, set CLAUDE_CODE_FORK_SUBAGENT to "0" in the env of your Claude Code settings, then start a new session. Claude can then wait for a subagent, and CORA’s instructions ask it to run the fixer in the foreground. The setting turns off fork mode, in which Claude starts forks of your conversation on its own, for the whole session, and your session then waits on the fixer until it returns; Ctrl+B moves it to the background if you want to keep working. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS set to "1" makes Claude wait for every subagent too, but it also removes background shell commands, so the fixer cannot keep your dev server running while it scans when a page’s server does not answer, and Ctrl+B moves nothing to the background.
• After 300 turns it stops, and returns its work marked as partial, which the main agent can resume.
• It can find, read and edit your project’s files, run commands, and call cora-mcp’s tools, and nothing else. Its edits and commands ask for your permission as your session’s permission mode and rules say.

In Codex

• It runs on your session’s model at high reasoning effort, with your session’s tools, sandbox and approval settings, which an agent file cannot change.
• It runs while the main agent works, and the main agent’s turn can end before its result arrives; the main agent sends it further edits with followup_task.
• To run it on another model than your session’s, set agents.default_subagent_model in your Codex config. Every subagent of yours then runs on that model, unless it names a model of its own.
• The main agent spawns it without your conversation’s history, with a brief of your request (Scans run in the fixer).
• The fixer takes its procedure from CORA’s hooks. Where the hooks do not run, it works from cora-mcp’s instructions and its tools’ descriptions alone.
• Codex starts a cora-mcp of its own for each agent, so the fixer has its own browser, which it closes before it returns.

The tool sequence

The fixer, or any agent that uses CORA’s tools, calls them in this order. Each tool’s entry in the MCP tools reference gives its arguments and its result.

1. To check a page in a state, open it with the browser_* tools and reach that state, such as an open dialog.
2. Scan the page as it is with scan_page, or load a URL and scan it with scan_url.
3. Where it needs to, list the rules the scan runs with list_rules.
4. Explain an issue with explain_finding.
5. Get how to fix each of its rules’ failures with get_fix_guidance.
6. Edit the code.
7. Check the fix with verify_fix, and take its next step: keep fixing, stop, or hand the issue to a person.
8. Last, report what became of each issue with summarize_fixes.

Each scan opens a record for each issue it finds, which verify_fix and summarize_fixes work through: see What cora-mcp writes.

The skills

The plugin’s skills are instructions an agent loads when its task calls for them. Claude Code and Codex both load them, under the plugin’s name:

Skill	Used by	What it does
cora:fix	you	Has the fixer carry out a request: see A first prompt.
cora:pause, cora:resume	you	Stop and restart the fixer’s start after UI edits: see Pausing and resuming CORA.
cora:a11y-remediation-loop	the fixer, as it starts	The fixer’s procedure: how it scans, fixes, verifies, proposes and summarizes.
cora:a11y-regression-tests	the fixer, and any agent that verifies a fix with verify_fix itself	Writes a test that pins a verified fix in your project’s own test framework, asserting the role, name or state a person using assistive technology meets, or proposes one.
cora:a11y-report	the main agent, when the fixer returns	Presents the fixer’s result: a headline count, the issues that need your decision first, the issues CORA marks as accepted by your baseline apart from the rest, the links for each issue, and “fixed and verified in a browser” for a fix CORA checked. It never claims that a page is compliant or accessible.
cora:a11y-check-ui-edits	the main agent, after it edits UI files	Has the fixer check the edits where CORA’s hooks do not ask for it: see The check after UI edits.

• Only you invoke cora:fix, cora:pause and cora:resume: type / before the name in Claude Code, and $ in Codex.
• You never invoke cora:a11y-remediation-loop: other agents dispatch the fixer instead.
• An agent also loads cora:a11y-regression-tests when you ask for accessibility regression tests.
• The fixer never loads cora:a11y-check-ui-edits, since it checks its own edits.

Parts of the skills a11y-remediation-loop, a11y-report and a11y-regression-tests adapt content from accessibility-agents, under the MIT License. Its notice sits beside them, in dist/harness/skills/NOTICE.md, and in @vispero/cora’s ThirdPartyNotices.txt.

The fixer’s progress

npx cora status shows where each issue stands while the fixer works on it, as Checking the account, the scans and the fixes describes.

In Claude Code, the plugin shows the same progress in the fixer’s row of the panel below the prompt, which lists the running agents:

cora:a11y-fixer · 1 in progress, 2 not attempted, 1 done · last still-failing after 2 attempts: axe/button-name at button.icon

• The row gives the issues by where each stands. While one is in progress, it adds the one the fixer checked last, with its latest verdict, its attempts, its rule and its element. It is cut to the panel’s width.
• Before the fixer’s first scan finds an issue, and once its summary has reported them, the row is Claude Code’s own: the agent’s task and its token count.
• The plugin sets Claude Code’s subagentStatusLine setting. It runs the project’s node_modules/.bin/cora every few seconds while an agent’s row shows, from the directory you started Claude Code in. It needs no account.
• Other agents’ rows keep Claude Code’s own. So does the fixer’s where the hooks do nothing, such as in a project without @vispero/cora (The plugin’s hooks).
• A subagentStatusLine of your own, in your Claude Code settings, replaces the plugin’s. Claude Code runs either only in a folder you trusted, and not while disableAllHooks is set.