Accessibility and screen-reader mode

Claude Code 2.1.215 adds a first-class terminal accessibility mode selected by --ax-screen-reader, CLAUDE_AX_SCREEN_READER, or the axScreenReader setting. The mode is more than a label: it changes renderer selection, animation behavior, terminal setup, startup output, and child-process environment propagation.

The ordinary classic/fullscreen selection, raw-input parser, resize/suspend handling, and terminal cleanup are documented in Terminal UI renderer and input lifecycle. This page owns only the accessibility-specific override and rendering behavior.

The exact CLAUDE_AX_SCREEN_READER and axScreenReader anchors are absent from the retained 2.1.143 parent bundle, so this page documents a package-delta subsystem rather than a renamed pre-existing path.

Source anchors

Semantic alias	Approximate location in `cli.renamed.js`	Exact string or symbol	Meaning
ScreenReaderSetting	~70,214	`axScreenReader`	Persistent setting with the flat-text/no-decoration description.
ScreenReaderResolver	~187,645-187,692	`class $Bc`, `RM`, `NBc`, `vrt`	Resolves activation, reports its source, and propagates the mode to child environments.
ScreenReaderGate	~187,658	`tengu_ax_screen_reader`	Feature gate that can veto an otherwise requested mode.
BooleanParsers	~1, ~27,000	`qt`, `gu`, `Pe.triBool()`	Trimmed, case-insensitive true/false parsing with `undefined` for an unrecognized value.
RendererSelection	~196,890-196,960	`sr_auto_off`	Forces the classic/default renderer instead of fullscreen rendering.
TerminalSetupGuard	~621,073-621,126	`screen-reader mode leaves the audible bell setting unchanged`	Preserves an audible terminal cue during newline-key setup.
StartupAnnouncement	~932,482	`[Screen Reader Mode: on via ...]`	Announces activation on an interactive TTY.
RootFlag	~958,910	`--ax-screen-reader`	User-facing root CLI switch.

Activation and precedence

The resolver evaluates sources in this order:

--ax-screen-reader enables the mode.
CLAUDE_AX_SCREEN_READER supplies a tri-state environment override; an explicit false value can override the setting.
axScreenReader: true in merged settings enables the mode when neither higher-priority source decided it.
tengu_ax_screen_reader is evaluated last and can gate the requested mode off.

Pe.triBool() uses the shared qt()/gu() parsers. Values are trimmed and compared case-insensitively:

Result	Accepted environment values
`true`	`1`, `true`, `yes`, `on`
`false`	`0`, `false`, `no`, `off`
`undefined`	missing or any other value

The resolver caches both the resulting decision and its flag, env, or settings source. Subsequent calls reuse that snapshot until $Bc.reset() clears it; changing argv, env, settings, or the gate after the first resolution is not by itself enough to recompute the mode. The feature gate is a final veto, not another positive source: a requested mode can resolve off when tengu_ax_screen_reader is disabled. When the final result is enabled, NBc() exposes the remembered source for the startup announcement and vrt() adds CLAUDE_AX_SCREEN_READER=1 to covered child environments.

flowchart LR
    Flag[--ax-screen-reader] --> Resolve[ScreenReaderResolver]
    Env[CLAUDE_AX_SCREEN_READER] --> Resolve
    Setting[axScreenReader] --> Resolve
    Resolve --> Gate[tengu_ax_screen_reader]
    Gate -->|enabled| Classic[Classic flat renderer]
    Gate -->|vetoed| Normal[Normal renderer selection]
    Classic --> Child[Child env: CLAUDE_AX_SCREEN_READER=1]

Renderer behavior

Runtime surface	Screen-reader behavior
Renderer selection	`Zi()` and `i7t()` return false; `N5e()` reports `sr_auto_off`. Fullscreen/flicker-free rendering is therefore not selected even if the `tui` setting requests it.
Presentation	The public setting/flag description promises flat text with no decorative borders or animations. The runtime also tells `/tui` users that screen-reader mode always uses the classic renderer.
Motion	Animated UI components consult the screen-reader state and settle immediately instead of continuing color/spinner animation.
Startup	Interactive TTY startup emits `[Screen Reader Mode: on via flag
Terminal key setup	The macOS newline-key setup skips changing the audible bell because the bell is useful feedback in this mode.
Fullscreen promotion	Fullscreen renderer upsell/downsell paths are suppressed while screen-reader mode is active.

What the mode does not change

Screen-reader mode is a rendering/accessibility selector, not a restricted execution mode. The source does not show it disabling model calls, tools, permissions, hooks, MCP, settings, or session persistence. Those boundaries continue to behave normally.

It is also distinct from prefersReducedMotion: reduced motion can stop animation without forcing the classic renderer, while screen-reader mode does both.

Caveats

The analyzed implementation is the terminal TUI path. It does not claim to configure OS accessibility APIs or desktop-app accessibility settings.
The source promises flat text, no decorative borders, and no animations; it does not promise that every color escape is removed.
An unrecognized CLAUDE_AX_SCREEN_READER value is not an explicit false override; tri-state parsing returns undefined, allowing the settings source to decide.
Approximate line anchors are build-specific. Search for CLAUDE_AX_SCREEN_READER, sr_auto_off, and tengu_ax_screen_reader when analyzing a later package.

Created and maintained by Yingting Huang.