Python / CLI

a11y-assist, recovery plans for everyone.

Deterministic accessibility assistance for CLI failures. Five profiles, SAFE-only commands, anchored error IDs, and disclosed confidence — never rewrites tool output, only adds a structured ASSIST block.

Get started Read the Handbook

Install

pip install a11y-assist

Wrap

assist-run some-tool do-thing

Assist

a11y-assist last --profile cognitive-load

Why a11y-assist?

Error recovery that adapts to how you work.

SAFE-Only Commands

Only read-only, dry-run, and status-check commands are ever suggested. No destructive operations, ever.

Five Profiles

Low vision, cognitive load, screen reader, dyslexia, and plain language. Each adapts output structure, step count, and phrasing.

Anchored Error IDs

Suggestions link back to the original error ID when available. No fabricated IDs, no invented content.

Confidence Disclosed

High, Medium, or Low — always shown, can decrease but never increase. You know how much to trust each suggestion.

Additive Only

Original tool output is never modified, hidden, or suppressed. a11y-assist only adds a structured ASSIST block.

Deterministic

Same input always produces the same output. No network calls, no randomness, no model invocations.

Quick Start

Wrap & assist

pip install a11y-assist

# Wrap any command
assist-run some-tool do-thing

# If it fails, get recovery guidance
a11y-assist last

# Switch profiles
a11y-assist last --profile cognitive-load

Structured input

# High-confidence from cli.error.v0.1 JSON
a11y-assist explain --json error.json

# Best-effort from raw text
some-tool 2>&1 | a11y-assist triage --stdin

# Import evidence-engine findings
a11y-assist ingest findings.json --verify-provenance

Commands

Command

Description

a11y-assist explain --json <path>

High-confidence assist from cli.error.v0.1 JSON

a11y-assist triage --stdin

Best-effort assist from raw CLI text

a11y-assist last

Assist from the last captured log

a11y-assist ingest <findings.json>

Import findings from a11y-evidence-engine

assist-run <cmd> [args...]

Wrapper that captures output for last

Accessibility Profiles

Five profiles ship out of the box.

Profile

Primary Benefit

Max Steps

lowvision (default)

Visual clarity — clear labels, numbered steps, SAFE commands

cognitive-load

Reduced mental steps — Goal line, First/Next/Last labels

screen-reader

Audio-first — TTS-friendly, abbreviations expanded

3–5

dyslexia

Reduced reading friction — explicit labels, no symbolic emphasis

plain-language

Maximum clarity — one clause per sentence, simplified structure

Confidence Levels

Always disclosed, never inflated.

Level

Meaning

When

High

Validated cli.error.v0.1 JSON with ID

Tool emits structured error output

Medium

Raw text with detectable (ID: ...)

Error ID found in unstructured text

Low

Best-effort parse, no ID found

No anchor — suggestions are heuristic

Safety Guarantees

Enforced at runtime by the Profile Guard system.

Invariant

Guarantee

SAFE-only commands

Only read-only, dry-run, and status-check commands suggested

No invented IDs

Error IDs come from input or are absent — never fabricated

No invented content

Profiles rephrase but never add new factual claims

Confidence disclosed

Always shown; can decrease but never increase

Additive only

Original tool output never modified, hidden, or suppressed

Deterministic

Same input, same output — no network, no randomness

Guard-checked

Every profile transform validated against invariants before rendering