# Getting Started

This guide covers installation and setup for all supported platforms: Claude Code, GitHub Copilot (VS Code and CLI), Gemini CLI, Claude Desktop, and Codex CLI.

## Building the 5.0 Native CLI

Accessibility Agents 5.0 introduces a Go-based native CLI layer for `gh skill setup`, `gh skill health`, `gh skill repair`, and `gh skill hooks`. End users do not need Go to consume released binaries, but contributors and release engineers need Go installed to build and validate those executables locally.

### Windows

Install Go with WinGet:

```powershell
winget install --id GoLang.Go --exact --accept-package-agreements --accept-source-agreements
```

Open a new terminal and verify:

```powershell
go version
```

Build the Windows binaries from the repository root:

```powershell
pwsh -NoProfile -File scripts/build-go-cli.ps1
```

This produces:

- `go-cli/bin/a11y-agents-setup.exe`
- `go-cli/bin/a11y-agents-health.exe`
- `go-cli/bin/a11y-agents-repair.exe`
- `go-cli/bin/a11y-agents-hooks.exe`

### macOS

Install Go with Homebrew:

```bash
brew install go
```

Verify the install:

```bash
go version
```

Build the macOS binaries from the repository root:

```bash
bash scripts/build-go-cli.sh
```

This produces native CLI binaries in `go-cli/bin/` with no `.pkg` packaging step required.

### Important Note About Node.js

Node.js is still required for the MCP server itself. It is not required to build or run the new Go-based setup, health, repair, and hooks utilities.

## Source Attribution

This guide is maintained against official platform documentation and release notes.

Key sources:

- VS Code updates: `https://code.visualstudio.com/updates`
- VS Code Copilot customization: `https://code.visualstudio.com/docs/copilot/customization/custom-instructions`
- VS Code custom agents: `https://code.visualstudio.com/docs/copilot/customization/custom-agents`
- VS Code prompt files: `https://code.visualstudio.com/docs/copilot/customization/prompt-files`
- GitHub Copilot docs: `https://docs.github.com/copilot`

When a setting or feature changes upstream, this guide should be updated with the corresponding source link.

---

## Markdown Accessibility CI Controls

The markdown accessibility scanner now supports repository-level configuration and machine-readable output.

### Repository Config File

Create `.a11y-markdown-config.json` in the repository root:

You can start from `templates/markdown-config-moderate.json`.

```json
{
  "ignoredDirs": ["node_modules", ".git", "dist", "build", "codex-skills"],
  "maxIssuesPerRule": 30,
  "failOn": "error",
  "rules": {
    "md-table-desc": { "enabled": true, "severity": "warning" },
    "md-link-ambiguous": { "enabled": true, "severity": "warning" },
    "md-emoji-heading": { "enabled": false, "severity": "warning" }
  },
  "output": {
    "format": "both",
    "sarifPath": "artifacts/markdown-a11y.sarif"
  }
}
```

### CLI Usage

```bash
node .github/scripts/markdown-a11y-lint.mjs . --fail-on error --format both --output artifacts/markdown-a11y.sarif
node .github/scripts/markdown-a11y-lint.mjs . --config .a11y-markdown-config.json --fail-on warning
```

### CI Enforcement Modes

`a11y-check.yml` supports these markdown gate modes:

- `none`: report only, never fail the markdown lint job
- `error`: fail only on error-level findings
- `warning`: fail on warnings and errors

Set default behavior with repository variables:

- `A11Y_MARKDOWN_FAIL_ON` = `none|error|warning`
- `A11Y_MARKDOWN_FORMAT` = `text|sarif|both`

For regression-only gating in CI:

- `A11Y_REGRESSION_MODE` = `true|false`

When enabled, the markdown scanner only gates on files changed since the baseline reference (default `HEAD~1`).

You can override both via `workflow_dispatch` inputs when running the workflow manually.

### Release and Version Safety Checks (v5.3+)

The `release-consistency-guard.yml` workflow enforces:

- version alignment across `plugin.yaml`, `gemini-extension.json`, `mcp-server/package.json`, and `manifest.json`
- required `CHANGELOG.md` entry for the current version
- required `RELEASE-{version}.md` file with `Overview`, `Highlights`, and `Full Changelog` sections

If any check fails, the workflow fails and blocks release progression.

### CI Integrity Guard Rails

The `ci-integrity-guards.yml` workflow validates:

- workflow invariants across critical CI files
- schema/template/settings drift for markdown, office, PDF, and EPUB config files
- documentation version pin freshness in release-facing examples

See [CI Integrity Guards](guides/ci-integrity-guards.md) for local commands and extension patterns.

### Editor Schema Assistance

Version 5.3 includes schema-backed editor validation for config files through `.vscode/settings.json`:

- `.a11y-markdown-config.json`
- `.a11y-office-config.json`
- `.a11y-pdf-config.json`

This enables JSON completion and immediate validation feedback while editing config files.

---

## Claude Code Setup

This is for the **Claude Code CLI** (the terminal tool). If you want the Claude Desktop app extension, skip to [Claude Desktop Setup](#claude-desktop-setup) below.

### How It Works

The accessibility agents are installed as Claude Code agents with a three-hook enforcement gate. You do not need to invoke them manually. The hooks automatically detect web projects and block UI file edits until accessibility-lead has been consulted.

The enforcement flow:

1. **Proactive detection** — A `UserPromptSubmit` hook checks your project directory for web framework indicators (`package.json` with React/Next/Vue, config files, `.tsx`/`.jsx` files). In a web project, the delegation instruction fires on every prompt — even "fix the bug."
2. **Edit gate** — A `PreToolUse` hook blocks any Edit/Write to UI files (`.jsx`, `.tsx`, `.vue`, `.css`, `.html`, etc.) until the accessibility-lead agent has completed a review. The tool call is denied at the system level using `permissionDecision: "deny"`.
3. **Session marker** — A `PostToolUse` hook creates a session marker when accessibility-lead completes. This unlocks the edit gate for the rest of the session.

The team includes twenty-five agents: nine web code specialists that write and review code, six document accessibility specialists that scan Office and PDF files, one document accessibility wizard that runs guided document audits (with two hidden helper sub-agents for parallel scanning), one markdown documentation accessibility orchestrator (markdown-a11y-assistant) that audits .md files across nine accessibility domains (with two hidden helper sub-agents for parallel scanning and fix application), one orchestrator that coordinates them, one interactive wizard that runs guided web audits (with two hidden helper sub-agents for page crawling and parallel scanning), one testing coach that teaches you how to verify accessibility, and one WCAG guide that explains the standards themselves. Three reusable agent skills provide domain knowledge.

For tasks that do not involve UI code (backend logic, scripts, database work), the hooks stay silent and the agents are not invoked.

### Prerequisites

> ⚠️ **IMPORTANT:** Always use the **latest versions** of all tools. Accessibility Agents rely on current platform APIs, new capabilities, and bug fixes. Outdated tools may cause unexpected behavior or missing functionality.

**Required:**

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and working (latest version)
- A Claude Code subscription (Pro, Max, or Team)
- **macOS:** bash 3.2+ is supported, including the system-provided `/bin/bash`
- **Windows:** PowerShell 5.1+ (pre-installed on Windows 10/11)

**Version Checks:**

```bash
claude code --version    # Should show latest stable release
bash --version          # macOS only
```

**How to Update:**

```bash
# Update Claude Code CLI
claude code update

# Update Accessibility Agents repository
cd accessibility-agents
git pull origin main

# Update GitHub Skills extension
gh extension upgrade gh-skill
```

### Installation

Use the GitHub Skills installer path:

```bash
gh skill install Community-Access/accessibility-agents
gh skill setup Community-Access/accessibility-agents
```

Validate and repair as needed:

```bash
gh skill health Community-Access/accessibility-agents
gh skill repair Community-Access/accessibility-agents
```

To uninstall:

```bash
gh skill uninstall Community-Access/accessibility-agents
```

Legacy script installers and uninstallers were removed in this branch.

#### Manual Setup

If you prefer to install manually or need to integrate into an existing configuration:

##### 1. Copy agents

```bash
# For project install
mkdir -p .claude/agents
cp -r path/to/a11y-agent-team/.claude/agents/*.md .claude/agents/

# For global install
mkdir -p ~/.claude/agents
cp -r path/to/a11y-agent-team/.claude/agents/*.md ~/.claude/agents/
```

##### 2. Copy enforcement hooks (global install only)

```bash
mkdir -p ~/.claude/hooks
cp path/to/accessibility-agents/claude-code-plugin/scripts/a11y-team-eval.sh ~/.claude/hooks/
cp path/to/accessibility-agents/claude-code-plugin/scripts/a11y-enforce-edit.sh ~/.claude/hooks/
cp path/to/accessibility-agents/claude-code-plugin/scripts/a11y-mark-reviewed.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/a11y-*.sh
```

Then register the hooks in `~/.claude/settings.json` (see the [Hooks Guide](hooks-guide.md) for the full JSON).

##### 3. Verify

Start Claude Code and type `/agents`. You should see all agents listed. Then verify enforcement:

1. Open a web project (anything with `package.json` containing React/Next/Vue/etc.)
2. Type any prompt — you should see `DETECTED: This is a web project` in the system reminder
3. If Claude tries to edit a `.tsx` file without consulting accessibility-lead, it should be blocked with `BLOCKED: Cannot edit UI file...`

### Using the Agents in Claude Code

Invoke any agent by name using the slash command or `@` mention:

```text
/accessibility-lead full audit of the checkout flow
/aria-specialist review the ARIA in components/modal.tsx
/contrast-master check all color combinations in globals.css
/keyboard-navigator audit tab order on the settings page
/web-accessibility-wizard run a full guided accessibility audit
/document-accessibility-wizard audit all documents in the docs/ folder
/testing-coach how do I test this modal with NVDA?
/wcag-guide explain WCAG 1.4.11 non-text contrast
```

To see all installed agents at any time, type `/agents` in Claude Code.

### Verifying Installation with Agent Debug Panel (VS Code 1.110+)

**VS Code users:** Use the **Agent Debug Panel** to verify all agents loaded correctly and see the three-hook enforcement system in action.

**Open the panel:**

- Command Palette → "Developer: Open Agent Debug Panel"
- Or: Copilot Chat view gear icon → "View Agent Logs"

**Check that you see:**

- **57 agents loaded** across all agent teams (web, document, GitHub, developer tools)
- **17 active skills** providing domain knowledge
- **3 workspace instructions** (web-accessibility-baseline, semantic-html, aria-patterns or powershell-terminal-ops depending on platform)
- **Hook execution** showing UserPromptSubmit, PreToolUse, and PostToolUse events during web UI tasks

If agents are missing or hooks are not firing, see the [Agent Debug Panel Guide](guides/agent-debug-panel.md) for troubleshooting workflows.

### Global vs Project Install

**Project-level** (recommended for teams): Install to `.claude/` in each web project. Check into version control so your whole team benefits. The agents travel with the repo.

**Global** (recommended for individuals): Install to `~/.claude/` to have the team available across all your projects automatically. Nothing to configure per-project. One install covers everything.

You can use both. Project-level agents override global agents with the same name, so you could customize an agent for a specific project while keeping the defaults globally.

### Auto-Updates (Claude Code)

During global installation, the installer asks if you want to enable auto-updates. When enabled, a daily scheduled job checks GitHub for new agent versions and installs them automatically.

- **macOS:** Uses a LaunchAgent (`~/Library/LaunchAgents/com.community-access.a11y-agent-team-update.plist`), runs daily at 9:00 AM
- **Windows:** Uses Task Scheduler (`A11yAgentTeamUpdate`), runs daily at 9:00 AM

Auto-updates keep both Claude Code agents (`~/.claude/agents/`) and Copilot agents in your VS Code user profile folder in sync.

Update log is saved to `~/.claude/.a11y-agent-team-update.log`.

You can also run updates manually at any time:

All platforms:

```bash
gh extension upgrade gh-skill
cd accessibility-agents
git pull origin main
```

Auto-updates are fully removed when you run the uninstaller.

### Safe Validation and CI

The repository includes two installer validation workflows:

- `installer-dry-run.yml` exercises shell and PowerShell dry-runs and validates summary schema fields
- `installer-integration.yml` runs real PowerShell project and global install/update/uninstall flows on Windows in disposable temp directories

The PowerShell integration workflow avoids touching the runner's real profile by overriding `USERPROFILE`, `APPDATA`, and `LOCALAPPDATA` with temporary directories before running global scenarios. Use the same technique locally when you want high-confidence validation without affecting your normal Claude or VS Code setup.

### OS Notifications for Long-Running Audits (VS Code 1.110+)

**VS Code users:** Configure OS notifications to stay informed during long-running accessibility audits, even when focused on other applications.

**Recommended Settings (VS Code):**

```jsonc
{
  // Notify when agent asks a question or needs confirmation
  "chat.notifyWindowOnResponseReceived": true,
  "chat.notifyWindowOnConfirmation": true,
  
  // Accessibility signal when user action is required
  "accessibility.signals.chatUserActionRequired": "on" // or "auto"
}
```

**When This Helps:**

- **Document audits:** Scanning 100+ Office or PDF files can take several minutes
- **Web wizard audits:** Multi-phase web accessibility workflows spanning 10+ minutes
- **GitHub briefings:** Background data collection across multiple repos
- **Long research phases:** Discovery and inventory building for cross-page analysis

**Accessibility Benefit:** Screen reader users hear an audio signal when an agent requires input, preventing missed questions during context switches.

**How to Configure:**

1. Open VS Code Settings (Ctrl/Cmd + ,)
2. Search for "chat notify"
3. Enable "Notify Window on Response Received" and "Notify Window on Confirmation"
4. Search for "accessibility signals chat"
5. Set "Chat User Action Required" to "on" or "auto"

### AI Co-Author Attribution (VS Code 1.110+)

**VS Code users:** Consider enabling AI co-author attribution to maintain transparency about AI contributions to your accessibility code.

**Recommended Setting:**

```jsonc
{
  // Add Co-authored-by: trailers to commits with AI-generated code
  "git.addAICoAuthor": "chatAndAgent"  // or "all" for completions too
}
```

**What It Does:**
Automatically adds a `Co-authored-by: GitHub Copilot <copilot@github.com>` trailer to git commit messages when code was generated or modified by AI agents.

**Benefits:**

- **Transparency:** Git history accurately reflects human + AI collaboration
- **Compliance:** Aligns with emerging AI attribution standards
- **Auditing:** Clear record of which accessibility fixes came from agents vs manual review

**Options:**

- `"chatAndAgent"` - Only for chat-generated and agent-generated code (recommended)
- `"all"` - Includes inline completions and suggestions
- `"never"` - No attribution (default)

**How to Configure:**

1. Open VS Code Settings (Ctrl/Cmd + ,)
2. Search for "git.addAICoAuthor"
3. Set to `"chatAndAgent"` or `"all"`

**Example Commit:**

```html
fix: Add ARIA labels to navigation menu controls

Co-authored-by: GitHub Copilot <copilot@github.com>
```

---

## GitHub Copilot Setup

This is for **GitHub Copilot Chat** in VS Code (or other editors that support the `.github/agents/` format).

### How It Works

GitHub Copilot supports custom agents via `.github/agents/*.agent.md` files and workspace-level instructions via `.github/copilot-instructions.md`. The A11y Agent Team provides:

- **Twenty-five specialist agents** that you can invoke by name in Copilot Chat
- **Workspace instructions** that remind Copilot to consider accessibility on every UI task
- **PR review instructions** (`.github/copilot-review-instructions.md`) that enforce accessibility standards during Copilot Code Review on pull requests
- **Commit message instructions** (`.github/copilot-commit-message-instructions.md`) that guide Copilot to include accessibility context in commit messages
- **PR template** (`.github/PULL_REQUEST_TEMPLATE.md`) with an accessibility checklist for every pull request
- **CI workflow** (`.github/workflows/a11y-check.yml`) that runs automated accessibility checks on PRs
- **VS Code configuration** (`.vscode/`) with recommended extensions, settings, tasks, and MCP server config

The workspace instructions in `.github/copilot-instructions.md` are automatically loaded into every Copilot Chat conversation, ensuring accessibility guidance is always present.

### Prerequisites

> ⚠️ **IMPORTANT:** Always use the **latest versions** of VS Code and GitHub Copilot extensions. New features (browser tools, enhanced context, improved tool use) and bug fixes directly impact agent capabilities.

**Required:**

- [GitHub Copilot](https://github.com/features/copilot) subscription (Individual, Business, or Enterprise)
- **VS Code:** Latest stable release ([Download](https://code.visualstudio.com/))
- **GitHub Copilot Extension:** Latest version from VS Code Marketplace
- **GitHub Copilot Chat Extension:** Latest version from VS Code Marketplace
- Agent mode and custom agents enabled in VS Code settings

**Version Checks:**

```bash
code --version    # Should show latest stable VS Code release
```

**How to Update:**

```bash
# Update VS Code: Help → Check for Updates
# Or enable auto-updates: File → Preferences → Settings → search "update mode"

# Update Extensions: Extensions → @installed → Update next to GitHub Copilot extensions

# Update Accessibility Agents
cd accessibility-agents
git pull origin main
gh extension upgrade gh-skill
```

### Installation

#### Option 1: Global (via the installer)

The easiest way to get Copilot agents in every workspace.

```bash
gh skill install Community-Access/accessibility-agents
gh skill setup Community-Access/accessibility-agents
```

This installs Copilot agents to your VS Code user profile folder. After installing, reload VS Code and open Copilot Chat. The agents will appear in the agent picker dropdown across all workspaces.

> **First use:** After installation, open the agent picker dropdown (the model/agent selector at the top of the Copilot Chat panel) and select the agent you want to use. Custom agents do not appear in `@` autocomplete until you have selected them from the picker at least once.

#### Option 2: Per-project

Copy the `.github` directory into your project so the agents travel with the repo.

```bash
git clone https://github.com/Community-Access/accessibility-agents.git
cd a11y-agent-team
cp -r .github /path/to/your/project/
```

Or run setup inside that project:

```bash
cd /path/to/your/project
gh skill setup Community-Access/accessibility-agents --scope project
```

#### Option 3: Per-project (via a11y-copilot-init)

If you installed globally with `--copilot`, run `a11y-copilot-init` inside any project to copy the agents:

```bash
cd /path/to/your/project
a11y-copilot-init
```

### Using the Agents in Copilot Chat

> **Important:** Custom agents must first be selected from the **agent picker dropdown** at the top of the Copilot Chat panel. They will not appear when typing `@` in the chat input until you have selected them from the picker at least once. This is standard VS Code behavior for custom agents, not specific to this project.

Once an agent has been picked, you can mention it by name to invoke it:

```text
@accessibility-lead full audit of the checkout flow
@aria-specialist review the ARIA in components/modal.tsx
@contrast-master check all color combinations in globals.css
@web-accessibility-wizard run a full guided accessibility audit of this project
@document-accessibility-wizard scan all documents in the docs/ folder
@testing-coach how should I test this component with VoiceOver?
@wcag-guide what changed between WCAG 2.1 and 2.2?
```

The workspace instructions in `.github/copilot-instructions.md` are loaded into every Copilot Chat conversation. When you ask Copilot to build or modify UI code, it will automatically consider accessibility requirements.

### MCP Server Setup (Required for MCP Tools)

The MCP server for document and PDF scanning lives in the top-level `mcp-server/` directory. This is the executable server that provides tools such as `scan_pdf_document` and `scan_office_document`.

**Install the MCP server dependencies first:**

The MCP server needs Node.js 18 or later plus npm. If you use the repository installers, they now detect missing Node.js and offer to install it before attempting `npm install`.

Manual fallback: <https://nodejs.org/en/download>

```bash
cd mcp-server
npm install
```

This installs the `@modelcontextprotocol/sdk` and `zod` packages that the server needs. The `node_modules/` directory is gitignored, so you must run this step after every fresh clone.

**Run the server locally:**

```bash
npm start
# -> http://127.0.0.1:3100/mcp
```

**Or use stdio mode for desktop clients:**

```bash
node stdio.js
```

**Verify the server loads:**

After running `npm install`, connect your client to the MCP server and reload the client if needed. If you see an error about missing packages, re-run `npm install` in the `mcp-server/` directory. If `node --version` is below 18, upgrade Node.js first.

**Prerequisite matrix:**

| Class | Requirement | Needed For | Required? |
|------|-------------|------------|-----------|
| Runtime | Node.js 18+ | Running the MCP server | Yes |
| Runtime | npm | Installing MCP server dependencies | Yes |
| Runtime | `@modelcontextprotocol/sdk`, `zod` | Baseline MCP tool availability | Yes |
| Client | MCP-compatible client | Calling MCP tools | Yes |
| Optional feature | Java 11+ + `verapdf` | Deep PDF validation with `run_verapdf_scan` | No |
| Optional feature | `playwright`, `@axe-core/playwright`, Chromium | Live browser scanning tools | No |
| Optional feature | `pdf-lib` | PDF form conversion | No |
| Installer-only | `git` | Clone-based install and update paths | No |
| Installer-only | Python 3 | Some shell-installer automation and fallback smoke-test logic | No |

Python is not required to use the MCP server. It is only used by some shell installer paths on macOS to automate config edits and fallback checks. On Windows, the PowerShell installer does not depend on Python.

**Guided MCP setup:**

The installer now walks you through MCP setup by capability profile instead of treating every optional tool the same.

| Profile | What it sets up |
|------|-------------------|
| `Baseline scanning` | MCP server, core npm dependencies, local MCP wiring |
| `Browser testing` | Baseline plus Playwright, axe-core, and Chromium |
| `PDF-heavy workflow` | Baseline plus `pdf-lib` and deeper PDF validation guidance |
| `Everything` | All supported MCP capabilities in one pass |
| `Custom` | Lets you choose browser tools, PDF form conversion, deep PDF validation guidance, and VS Code MCP registration individually |

During guided setup, the installer also warns about capability-specific prerequisites before it installs anything:

- Browser testing needs Playwright, axe-core, and Chromium.
- PDF form conversion needs `pdf-lib`.
- Deep PDF validation needs Java 11+ and `verapdf`, but baseline PDF scanning still works without them.
- Python is never required for MCP runtime.

If you skip an optional capability, the installer leaves the MCP server usable and tells you exactly how to enable that capability later.

For the shortest PDF-only path, see [mcp-server/PDF-QUICKSTART.md](../mcp-server/PDF-QUICKSTART.md).

**What the MCP server provides:**

| Tool | Purpose |
|------|---------|
| `check_contrast` | Calculate WCAG contrast ratios between hex colors |
| `get_accessibility_guidelines` | Get WCAG AA guidelines for specific component types |
| `check_heading_structure` | Analyze HTML heading hierarchy |
| `check_link_text` | Detect ambiguous link text |
| `check_form_labels` | Validate form input label associations |
| `generate_vpat` | Generate VPAT 2.5 conformance report |
| `run_axe_scan` | Run axe-core against a live URL |
| `run_playwright_keyboard_scan` | Detect keyboard traps and focus-order issues |
| `run_playwright_viewport_scan` | Check viewport reflow and touch-target risk |
| `run_playwright_contrast_scan` | Validate rendered contrast from computed styles |
| `run_playwright_a11y_tree` | Capture browser accessibility tree snapshots |
| `scan_office_document` | Scan DOCX, XLSX, PPTX for accessibility issues |
| `scan_pdf_document` | Scan PDFs for PDF/UA conformance |

### High-Impact Playwright Workflow

For runtime regressions with significant user impact, use:

- `.github/workflows/playwright-high-impact-check.yml`
- `mcp-server/scripts/playwright-high-impact-check.mjs`

This check focuses on serious accessibility failures, keyboard traps, viewport overflow, and touch target risk. See [Playwright High-Impact Checks](guides/playwright-high-impact-checks.md).

### Differences from Claude Code

| Feature | Claude Code | GitHub Copilot |
|---------|-------------|----------------|
| Agent location | `.claude/agents/` | `.github/agents/` |
| Activation | `.github/copilot-instructions.md` | `.github/copilot-instructions.md` |
| PR review | N/A | `.github/copilot-review-instructions.md` |
| Commit messages | N/A | `.github/copilot-commit-message-instructions.md` |
| PR template | N/A | `.github/PULL_REQUEST_TEMPLATE.md` |
| CI workflow | N/A | `.github/workflows/a11y-check.yml` |
| VS Code config | N/A | `.vscode/` (extensions, settings, tasks, MCP) |
| Invocation | `/agent-name` or `@agent-name` | `@agent-name` |
| Auto-activation | Invoke agents directly | Workspace instructions provide guidance |
| Global install | `~/.claude/agents/` | VS Code user profile folder or per-project |

---

## GitHub Copilot CLI Setup

This is for **GitHub Copilot CLI** - the terminal-native agent interface. If you want the VS Code extension, see [GitHub Copilot Setup](#github-copilot-setup) above.

### How It Works

GitHub Copilot CLI is a standalone terminal application that runs Copilot directly in your shell. It supports custom agents via `.github/agents/*.agent.md` files and skills via `.github/skills/*/SKILL.md` folders.

The accessibility agents work in Copilot CLI with these capabilities:

- **Agent invocation** via `/agent` command or natural language
- **Skill loading** for domain-specific knowledge (accessibility rules, WCAG reference)
- **Tool access** for file reading, editing, searching, and command execution

### Prerequisites

**Required:**

- [GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) installed
- An active Copilot subscription
- **Windows:** PowerShell v6 or higher

**Installation:**

```bash
# npm (all platforms)
npm install -g @github/copilot

# Homebrew (macOS)
brew install copilot-cli

# WinGet (Windows)
winget install GitHub.Copilot
```

### Agent Discovery Paths

Copilot CLI discovers agents from these locations:

| Type | Path | Scope |
|------|------|-------|
| Repository | `.github/agents/*.agent.md` | Current project only |
| User | `~/.copilot/agents/*.agent.md` | All projects |
| Organization | `.github-private/agents/` | Organization-wide |

### Skill Discovery Paths

Skills provide domain knowledge that agents can load when relevant:

| Type | Path | Scope |
|------|------|-------|
| Repository | `.github/skills/*/SKILL.md` | Current project only |
| User | `~/.copilot/skills/*/SKILL.md` | All projects |

### Installation

#### Option 1: Repository-level (Per-project)

Clone or copy the accessibility agents into your project:

```bash
# Clone the repo
git clone https://github.com/Community-Access/accessibility-agents.git

# Copy agents and skills to your project
cp -r accessibility-agents/.github/agents /path/to/your/project/.github/
cp -r accessibility-agents/.github/skills /path/to/your/project/.github/
```

#### Option 2: User-level (Global)

Install agents globally so they're available in all projects:

```bash
# Create directories if they don't exist
mkdir -p ~/.copilot/agents
mkdir -p ~/.copilot/skills

# Copy agents
cp accessibility-agents/.github/agents/*.agent.md ~/.copilot/agents/

# Copy skills (each skill is a folder with SKILL.md inside)
cp -r accessibility-agents/.github/skills/* ~/.copilot/skills/
```

Or use setup mode after installing the skill:

```bash
gh skill setup Community-Access/accessibility-agents
```

### Using Agents in Copilot CLI

**List available agents:**

```bash
/agent
```

**Use an agent directly:**

```bash
# Select from the agent picker
/agent

# Or mention the agent in your prompt
Use the accessibility-lead agent to review this component

# Or specify via command line
copilot --agent=accessibility-lead --prompt "Review the accessibility of src/components/"
```

**List and manage skills:**

```bash
/skills list        # Show available skills
/skills             # Toggle skills on/off interactively
/skills info        # Show skill details and locations
/skills reload      # Reload skills after adding new ones
```

### Tool Compatibility

Copilot CLI uses standardized tool aliases. The accessibility agents include tool declarations that work across platforms:

| CLI Tool | Purpose | Agent Usage |
|----------|---------|-------------|
| `read` | Read file contents | View source files for review |
| `edit` | Edit files | Apply accessibility fixes |
| `search` | Search files | Find accessibility patterns |
| `execute` | Run shell commands | Run axe-core scans |
| `agent` | Delegate to sub-agents | Coordinate specialist agents |
| `web` | Fetch web content | Retrieve WCAG documentation |

### Troubleshooting

**Agents not appearing in `/agent` list:**

1. Verify files are in correct location: `.github/agents/*.agent.md` or `~/.copilot/agents/*.agent.md`
2. Ensure workspace is trusted (CLI prompts on first use)
3. Check file naming: must end in `.agent.md`
4. Restart CLI session after adding new agents

**Skills not loading:**

1. Verify skill structure: `.github/skills/skill-name/SKILL.md`
2. Check SKILL.md has required YAML frontmatter with `name` and `description`
3. Run `/skills reload` to refresh after adding new skills
4. Use `/skills info` to check where skills are loaded from

**"Tool not found" errors:**

- Agents may reference VS Code-specific tools that CLI doesn't have. This is expected behavior.
- CLI ignores unknown tool names gracefully. Core functionality (read, edit, search) works.

**Agent not behaving as expected:**

1. Enable debug logging: `/troubleshoot` (requires VS Code 1.113-era Agent Debug settings for best results across local, Copilot CLI, and Claude agent sessions)
2. Check that instructions file is being loaded: `/instructions`
3. Verify workspace trust is granted for the project

For detailed troubleshooting, see [Copilot CLI Troubleshooting Guide](guides/copilot-cli-troubleshooting.md).

### Differences from VS Code Extension

| Feature | VS Code Extension | Copilot CLI |
|---------|-------------------|-------------|
| Agent picker | Dropdown in Chat panel | `/agent` command |
| Skills | Auto-loaded based on context | `/skills` to manage |
| Tools | Extension-specific (runSubagent, getDiagnostics) | Standard aliases (read, edit, search, agent) |
| Debugging | Agent Debug Panel | `/troubleshoot` command |
| Global agents | VS Code user profile folder | `~/.copilot/agents/` |
| Instructions | `.github/copilot-instructions.md` | Same (auto-loaded) |
| Model selection | Settings/dropdown | `/model` command |

### CLI-Specific Tips

**Autopilot mode for batch scans:**

Press `Shift+Tab` to cycle to Autopilot mode for hands-free accessibility audits:

```bash
# Start in autopilot mode
copilot --experimental
# Then Shift+Tab to cycle to autopilot
```

**Resume sessions:**

```bash
# Resume last session
copilot --continue

# List and select a session
/resume
```

**Include specific files:**

```bash
# Use @ to include files in context
Explain @src/components/Modal.tsx for accessibility issues
```

---

## Claude Desktop Setup

This is for the **Claude Desktop app** (the standalone application).

### What is the .mcpb Extension?

The `.mcpb` file (MCP Bundle) is Claude Desktop's extension format. It is a packaged bundle that adds tools and prompts directly into the Claude Desktop interface. You download one file, double-click it, and Claude Desktop installs it.

The A11y Agent Team extension adds:

**Tools** (Claude can call these automatically while working):

- **check_contrast**: Calculate WCAG contrast ratios between two hex colors
- **get_accessibility_guidelines**: Get detailed WCAG AA guidelines for specific component types
- **check_heading_structure**: Analyze HTML for heading hierarchy issues
- **check_link_text**: Scan HTML for ambiguous link text
- **check_form_labels**: Validate form inputs have proper label associations
- **generate_vpat**: Generate a VPAT 2.5 / Accessibility Conformance Report template
- **run_axe_scan**: Run axe-core against a live URL and return violations
- **scan_office_document**: Scan DOCX, XLSX, PPTX files for accessibility issues
- **scan_pdf_document**: Scan PDFs for PDF/UA conformance
- **extract_document_metadata**: Extract document properties and metadata
- **batch_scan_documents**: Scan multiple documents in one operation

**Prompts** (you select these from the prompt menu):

- **Full Accessibility Audit**: Comprehensive WCAG 2.1 AA review
- **ARIA Review**: Focused review of ARIA roles, states, and properties
- **Modal/Dialog Review**: Focus trapping, focus return, escape behavior
- **Color Contrast Review**: Color choices checked against AA requirements
- **Keyboard Navigation Review**: Tab order, focus management, skip links
- **Live Region Review**: Dynamic content announcements and screen reader compatibility

### Prerequisites

> ⚠️ **IMPORTANT:** Always use the **latest version** of Claude Desktop. Anthropic regularly adds new MCP capabilities, tool improvements, and features that enhance extension functionality.

**Required:**

- [Claude Desktop](https://claude.ai/download) app installed (latest version)
- A Claude subscription (Pro plan or higher)

**Version Checks:**

```bash
# Check Claude Desktop: About → Version (or Help menu)
```

**How to Update:**

```bash
# Claude Desktop auto-updates by default, or check Help → Check for Updates
# Update Accessibility Agents
cd accessibility-agents
git pull origin main
gh extension upgrade gh-skill
```

### How to Install

1. Go to the [Releases page](https://github.com/Community-Access/accessibility-agents/releases)
2. Download the latest `a11y-agent-team.mcpb` file
3. Double-click the file (or drag it into Claude Desktop)
4. Claude Desktop will open an install dialog. Click Install
5. Done. The tools and prompts are now available in every conversation

### How to Use in Claude Desktop

**Tools activate automatically.** When you ask Claude to review code or build a component, it can call `check_contrast` and `get_accessibility_guidelines` on its own.

**Prompts are available from the prompt menu.** Click the prompt picker (or type `/`) and you will see the six review prompts listed.

### Building from Source

```bash
npm install -g @anthropic-ai/mcpb
git clone https://github.com/Community-Access/accessibility-agents.git
cd a11y-agent-team/mcp-server
npm install
mcpb validate .
mcpb pack . ../a11y-agent-team.mcpb
```

The output file can be double-clicked to install in Claude Desktop.

---

## Codex CLI Setup

This is for **OpenAI Codex CLI** (the terminal coding agent).

### How It Works

Accessibility Agents ships for Codex as a direct skills pack under `codex-skills/`. The installer copies those 80 skills into `.codex/skills/` for project installs or `~/.codex/skills/` for global installs, which is currently more reliable than depending on the Codex plugin marketplace flow for community distributions.

This repo also includes an experimental TOML-based role layer for newer Codex builds that support multi-agent workflows. Those roles are optional and separate from the skills pack.

### Why Not the Codex Plugin Marketplace?

We originally implemented Accessibility Agents for Codex as a repo-local plugin package plus marketplace registration and tested it against current Codex plugin docs and app behavior.

What we verified during that research:

- Codex does have a curated plugins directory in the app.
- Local marketplace/plugin installation can work on a developer machine and Codex may cache the installed plugin under `~/.codex/plugins/cache/...`.
- Codex plugin packaging is documented by OpenAI, but we could not find a public self-serve submission or broad community distribution workflow for third-party plugins.

What did not hold up well enough for primary distribution:

- Third-party plugin discovery was less predictable than direct skills installs across fresh Codex sessions.
- Users often still had to install or confirm the plugin through the Codex app UI.
- The experience was not close enough to the one-step familiarity people get from Claude-style agent installs or direct skill packs.

Because of that, Codex support in this repo now uses the simpler and more dependable path: install the skills directly into `.codex/skills/` or `~/.codex/skills/`.

Research references:

- Codex curated plugins directory announcement: `https://help.openai.com/en/articles/11391654-chatgpt-business-release-notes`
- Codex usage and workspace app controls: `https://help.openai.com/en/articles/11369540`
- Codex plugin format sample: `https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md`

### Prerequisites

> ⚠️ **IMPORTANT:** Always use the **latest version** of Codex CLI. New OpenAI model capabilities, API changes, and bug fixes may affect agent behavior.

**Required:**

- [Codex CLI](https://github.com/openai/codex) installed and working (latest version)
- An OpenAI API key configured

**Version Checks:**

```bash
codex --version    # Should show latest stable release
```

**How to Update:**

```bash
# Update Codex CLI (follow official documentation)
# Update Accessibility Agents
cd accessibility-agents
git pull origin main
gh extension upgrade gh-skill
```

### Installation

#### Via GitHub Skill Setup (Recommended)

```bash
gh skill install Community-Access/accessibility-agents
gh skill setup Community-Access/accessibility-agents
```

The interactive installer also prompts for Codex support if you do not pass the flag. Codex installs include the 80-skill Accessibility Agents pack under `.codex/skills/` or `~/.codex/skills/` and, when available, the experimental `.codex/config.toml` plus `.codex/roles/*.toml` files.

#### One-Liner

```bash
gh skill install Community-Access/accessibility-agents && gh skill setup Community-Access/accessibility-agents
```

#### Manual Setup

```bash
# For project install
mkdir -p .codex/skills .codex/roles
cp -R path/to/accessibility-agents/codex-skills/. .codex/skills/
cp path/to/accessibility-agents/.codex/config.toml .codex/config.toml
cp path/to/accessibility-agents/.codex/roles/*.toml .codex/roles/

# For global install
mkdir -p ~/.codex/skills ~/.codex/roles
cp -R path/to/accessibility-agents/codex-skills/. ~/.codex/skills/
cp path/to/accessibility-agents/.codex/config.toml ~/.codex/config.toml
cp path/to/accessibility-agents/.codex/roles/*.toml ~/.codex/roles/
```

For project installs, commit `.codex/skills/` and optionally `.codex/config.toml` plus `.codex/roles/` so the Accessibility Agents skill pack and any experimental roles travel with the project together.

### Using Codex with Accessibility Rules

Once installed, the rules apply automatically. Just use Codex normally:

```bash
codex "Build a login form"
codex "Add a modal dialog to the settings page"
codex "Create a data table for the analytics dashboard"
```

Codex can use the Accessibility Agents skills directly from `.codex/skills/` or `~/.codex/skills/`. The experimental role files add narrower specialist passes when you want them.

For the current role list, install details, and limitations, see [Experimental Codex Multi-Agent Roles](guides/codex-experimental-multi-agent.md).

### Removing

```bash
gh skill uninstall Community-Access/accessibility-agents
```

---

## Gemini CLI Setup

This is for **Google Gemini CLI** (the terminal coding agent).

### How It Works

Gemini CLI uses an extension system with skills. Each accessibility agent is packaged as a skill (`SKILL.md` with YAML frontmatter) inside the `a11y-agents` extension. The `GEMINI.md` context file provides always-on WCAG AA enforcement rules that load into every conversation, similar to how `CLAUDE.md` works for Claude Code.

The extension includes 49 agent skills covering all accessibility domains plus 14 knowledge domain skills for reference data (WCAG mappings, severity scoring, help URLs).

### Prerequisites

> ⚠️ **IMPORTANT:** Always use the **latest version** of Gemini CLI. Google adds new model capabilities, API improvements, and features that enhance agent functionality.

**Required:**

- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and working (latest version)
- A Gemini API key configured

**Version Checks:**

```bash
gemini --version    # Should show latest stable release
```

**How to Update:**

```bash
# Update Gemini CLI (follow official documentation)
# Update Accessibility Agents
cd accessibility-agents
git pull origin main
gh extension upgrade gh-skill
```

### Installation

#### Via GitHub Skill Setup (Recommended)

```bash
gh skill install Community-Access/accessibility-agents
gh skill setup Community-Access/accessibility-agents
```

**Windows (PowerShell):**

The interactive installer also prompts for Gemini support.

#### One-Liner

```bash
gh skill install Community-Access/accessibility-agents && gh skill setup Community-Access/accessibility-agents
```

#### Manual Setup

```bash
# For project install
cp -r .gemini/extensions/a11y-agents/ /path/to/project/.gemini/extensions/a11y-agents/

# For global install
cp -r .gemini/extensions/a11y-agents/ ~/.gemini/extensions/a11y-agents/
```

For project installs, commit `.gemini/extensions/a11y-agents/` to your repo so the rules travel with the project.

### Using Gemini with Accessibility Skills

Once installed, skills are available automatically. Just use Gemini normally:

```bash
gemini "Build a login form"
gemini "Add a modal dialog to the settings page"
gemini "Create a data table for the analytics dashboard"
```

Gemini will load the `GEMINI.md` context file and apply WCAG AA rules to all UI code. Individual skills provide deeper domain-specific knowledge when triggered by relevant prompts.

### What's Included

- **gemini-extension.json** -- Extension manifest
- **GEMINI.md** -- Always-on accessibility context with decision matrix and non-negotiable standards
- **skills/** -- 63 skills total (49 agent skills + 14 knowledge domains)

### Removing

Delete the extension directory:

```bash
# Project install
rm -rf .gemini/extensions/a11y-agents/

# Global install
rm -rf ~/.gemini/extensions/a11y-agents/
```
