Accessibility Intelligence Agent

A terminal-based agent that scans source code for accessibility issues across Web, Android, and iOS platforms.

Built on the accessibility-intelligence skill with a 3-agent architecture:

• Planner – detects platforms, gathers files, creates a scan plan
• Executor – runs the plan, deduplicates and ranks findings
• Rules Engine – platform-specific regex-based accessibility checks

Quick Start

# Scan a directory (auto-detects platforms)
python3 -m agent scan ./your-project

# Scan only iOS files
python3 -m agent scan ./src --platform ios

# Preview the plan without scanning
python3 -m agent plan ./your-project

# Generate a saved Markdown report
python3 -m agent report ./your-project --format md

# Generate a JSON report to a specific file
python3 -m agent scan ./src --format json --output report.json

# Scan screenshots for visual accessibility issues
python3 -m agent screenshots ./screenshots --platform ios

Or use the wrapper script:

./a11y-agent scan ./your-project

Inter-Agent Communication

The agent can receive input from, and send output to, other agents using three modes:

1. Oneshot Request (Quick Testing)

# Process a single request from another agent
python3 -m agent serve -r '{"action":"scan","from_agent":"ci-agent","payload":{"path":"./src","platform":"ios"}}'

2. stdin/stdout Pipe (Pipeline Mode)

# Pipe from another agent
echo '{"action":"scan","payload":{"path":"./src"}}' | python3 -m agent serve

# Chain agents in a pipeline
planning-agent | python3 -m agent serve | fix-agent

3. File-Based (Async Multi-Agent)

# Watch inbox for requests, write responses to outbox
python3 -m agent serve --mode file --inbox ./inbox --outbox ./outbox

4. Python API (In-Process)

from agent import AccessibilityAgent

a11y = AccessibilityAgent()

# Register downstream agents to receive findings
a11y.on_findings("fix-agent", lambda msg: fix_agent.receive(msg))
a11y.on_findings("jira-agent", lambda msg: jira_agent.create_tickets(msg))

# Scan and auto-dispatch to registered agents
findings = a11y.scan("./src", platform="ios")

# Or process a message from another agent
response = a11y.receive({
    "action": "scan",
    "from_agent": "ci-pipeline",
    "payload": {"path": "./src", "platform": "ios"}
})

Message Schema

Request:

{
    "message_id": "optional-uuid",
    "from_agent": "requesting-agent-name",
    "to_agent": "accessibility-intelligence",
    "action": "scan | plan | report | screenshots | health",
    "payload": { "path": "./src", "platform": "ios" },
    "metadata": { "correlation_id": "trace-id" }
}

Response:

{
    "message_id": "uuid",
    "from_agent": "accessibility-intelligence",
    "to_agent": "requesting-agent-name",
    "status": "success | error",
    "payload": { "findings": [...], "total_issues": 8, "has_critical": true },
    "metadata": { "duration_ms": 1.2, "correlation_id": "trace-id" }
}

Commands

Command	Description
scan	Full pipeline: plan → execute → report (terminal output)
plan	Show analysis plan without executing the scan
report	Scan and save report to reports/ directory

Options

Flag	Description
--platform	Filter: web, android, or ios
--format	Output: terminal, json, or md
--output / -o	Custom output file path
--focus	Focus area hint for the planner

Supported Checks

Web

• Missing alt text on images
• Missing aria-label on interactive elements
• <div> used as button without semantics
• Missing form labels
• Heading order issues
• Missing lang attribute

Android

• Missing contentDescription
• Clickable without role
• Missing heading semantics
• Missing state descriptions
• Empty content descriptions

iOS

• Missing accessibilityLabel
• Missing accessibilityHint
• Missing accessibilityTraits on tap targets
• Images without labels
• Fixed font sizes (Dynamic Type)

Output

Reports follow the structured schema from SKILL.md — each finding includes:

• issue_id, platform, screen, issue_type
• severity (critical/high/medium/low)
• confidence score
• evidence (file, line, code snippet)
• description and recommended_fix

Exit Codes

• 0 – No critical/high issues found
• 1 – Critical or high severity issues detected (useful for CI)

Project Structure

hackathon-accessibility/
├── agent/
│   ├── __init__.py        # Public API exports
│   ├── __main__.py        # python -m agent entry point
│   ├── cli.py             # CLI argument parsing and commands
│   ├── config.py          # Configuration constants
│   ├── planner.py         # Planner agent
│   ├── executor.py        # Executor agent
│   ├── reporter.py        # Report generation (terminal/json/md)
│   ├── rules_engine.py    # Platform-specific accessibility rules
│   ├── image_analyzer.py  # Screenshot/UI visual analysis
│   └── protocol.py        # Inter-agent communication protocol
├── mcp_server.py          # MCP server for IDE integration
├── pyproject.toml         # Package config for pip/PyPI
├── mcp-config-example.json
├── references/
│   ├── accessibility-rules.md
│   ├── executor.md
│   └── planner.md
├── reports/               # Generated reports
├── samples/               # Sample files for testing
├── SKILL.md               # Skill definition
├── README.md
└── a11y-agent             # Shell wrapper

Distribution & Installation

Option 1: MCP Server (Recommended for AI IDEs)

Works with Kiro, Claude Desktop, Cursor, and any MCP-compatible tool.

Install:

pip install mcp

Configure your IDE — add to ~/.kiro/settings/mcp.json (Kiro) or claude_desktop_config.json:

{
  "mcpServers": {
    "accessibility-intelligence": {
      "command": "python3",
      "args": ["/path/to/hackathon-accessibility/mcp_server.py"],
      "disabled": false,
      "autoApprove": ["a11y_scan", "a11y_health"]
    }
  }
}

Once configured, your IDE can call these tools:

• a11y_scan — Scan code for accessibility issues
• a11y_scan_screenshots — Analyze screenshots for visual issues
• a11y_report — Generate and save a full report
• a11y_health — Check agent status

Option 2: PyPI Package (pip install)

Publish to PyPI so anyone can install with pip:

# Build the package
pip install build
python -m build

# Upload to PyPI
pip install twine
twine upload dist/*

# Then anyone can install:
pip install accessibility-intelligence
a11y-agent scan ./my-project --platform ios

Option 3: VS Code Extension (Marketplace)

For a full VS Code extension with UI panels, see the VS Code Extension API docs. The extension would spawn the Python agent as a subprocess and display results in the Problems panel.

Option 4: GitHub Action (CI/CD)

# .github/workflows/a11y.yml
name: Accessibility Check
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install accessibility-intelligence
      - run: a11y-agent scan ./src --platform ios --format json -o a11y-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: accessibility-report
          path: a11y-report.json