Claude Code Screen Reader Mode: Setup, Verification and Rollback

This setup and acceptance-test guide makes activation, verification, failure diagnosis, and rollback observable by the person who will use the workflow. It does not claim that every assistive-technology and terminal combination has been certified.

What screen reader mode changes

Anthropic announced the mode on July 20, 2026. The official thread says the flag replaces the visual terminal UI with plain linear text, then names transcript labels, numbered menus, a terminal bell, the environment variable, and the persistent setting.

The operational details below are based on Anthropic's current screen reader guide, settings reference, CLI reference, terminal guide, and Claude Code changelog, checked July 21, 2026. No cross-platform assistive-technology lab run was performed for this article. VoiceOver and NVDA are examples in Anthropic's documentation, not evidence of an exhaustive support matrix.

The current docs and changelog describe the version history differently. The accessibility page gives v2.1.181 as the minimum, while the changelog records “Added screen reader mode” under v2.1.208. This guide preserves both records. Use a current release instead of treating either entry as a reason to pin an older build.

Prerequisites and version baseline

Check the binary that your terminal will actually launch:

claude --version

The documented hard minimum is v2.1.181. A more useful rollout floor is v2.1.211 or later, because the intervening releases add or fix behavior relevant to acceptance testing:

For a native install, claude update follows the configured release channel. Homebrew, WinGet, and Linux package-manager installs normally use their package manager instead; Anthropic's installation guide lists the current commands. If the version remains old after an update, check for competing binaries with which -a claude on macOS/Linux or where.exe claude on Windows, as described in the installation troubleshooting guide.

You also need a terminal with usable scrollback and your normal assistive technology. Our Claude Code dynamic-workflows guide provides a broader tour of interactive sessions, requirements, and permission handling.

Fast path: one accessible session

Run:

claude --ax-screen-reader

On v2.1.206 or later, the first line should be:

[Screen Reader Mode: on via flag]

Versions from the documented minimum through v2.1.205 use the older confirmation [Accessible screen reader mode: on]. An unknown-option error means the running binary is too old or is not the binary you updated.

This flag affects the interactive terminal renderer. It does not install a screen reader, synthesize speech, alter the selected model, or change Claude Code's permission policy. Your assistive technology reads the linear terminal output.

Activation methods and precedence

Choose the narrowest scope that matches your use. Anthropic documents three activation methods, in this precedence order: flag, environment variable, settings.

For persistent user settings, merge the key into the existing JSON rather than replacing the file.

{
  "axScreenReader": true
}

The settings scope reference places personal preferences in user scope. Avoid committing this preference to a repository's .claude/settings.json: project settings are shared with every collaborator, while assistive-technology needs are personal. For SSH, set the variable or user setting on the remote machine, where the Claude Code process runs.

Precedence explains many confusing results. A launch flag wins over CLAUDE_AX_SCREEN_READER; the environment wins over the JSON setting. After Claude Code relaunches itself to finish an update, it passes the mode through the environment, so the new process can report on via env even when the original launch used the flag or setting. That documented relaunch behavior is not proof that your configuration changed.

Persistence and rollback

Rollback should be tested alongside enablement, especially on a shared or managed workstation.

For a one-launch override when settings enable the mode, use CLAUDE_AX_SCREEN_READER=0 claude in Bash/Zsh, or set $env:CLAUDE_AX_SCREEN_READER = "0" before launching from PowerShell. Anthropic explicitly documents that 0 keeps the mode off even when the setting is true. It cannot negate a positive --ax-screen-reader flag, which has higher precedence.

Inside Claude Code, /status shows which settings sources loaded. It does not identify which source supplied each individual key. If a settings file is malformed or rejected, run claude doctor for the source and validation error.

Screen reader and terminal setup

Screen reader mode does not auto-detect VoiceOver, NVDA, or another assistive technology. Turn it on explicitly, then test the exact combination the user relies on. Anthropic does not currently publish a certification table for JAWS, Orca, Braille displays, terminal multiplexers, or every terminal emulator; compatibility should not be inferred from the phrase “plain text.”

Do not confuse CLAUDE_AX_SCREEN_READER with CLAUDE_CODE_ACCESSIBILITY. The latter keeps the native terminal cursor visible for screen magnifiers such as macOS Zoom; it does not enable linear screen-reader output. The same accessibility reference documents prefersReducedMotion and the dark-daltonized and light-daltonized themes for separate needs. These controls can be used alongside screen reader mode.

The terminal changes how efficiently a user can revisit earlier turns:

The bell is the terminal's own alert. In screen reader mode it rings when Claude finishes a reply, a permission prompt appears, or a tool that ran longer than five seconds finishes. If an earlier Apple Terminal setup disabled it, update to v2.1.211 or later and re-enable Audible bell under Settings → Profiles → Advanced.

Test the host terminal independently. In Bash or Zsh, run:

printf '\a'

In PowerShell, run:

[Console]::Write("`a")

If that produces no audible or configured visual alert, fix the terminal before diagnosing Claude Code. The broader terminal configuration guide covers bell, desktop-notification, and tmux passthrough settings.

Expected behavior

When the mode is active, the interface becomes an accumulating terminal transcript rather than a continuously redrawn visual UI. Anthropic documents these observable changes:

• interface chrome has no box-drawing characters or color-only cues;
• unchanged content is not redrawn, and progress spinners become static text;
• messages begin with searchable labels such as you:, claude:, tool:, tool error:, error:, and Permission Required:;
• menus become numbered lists followed by an Enter selection prompt;
• yes-or-no prompts accept y, n, yes, or no;
• the terminal cursor follows the input caret;
• reply tables become Header: value sentences on v2.1.198 or later;
• fullscreen tui settings are ignored for the foreground screen-reader session.

This simplified transcript is still interactive. Tool permissions remain in force; they are presented as numbered choices rather than an arrow-key-oriented visual dialog. The mode improves access to the prompt but does not approve an action on the user's behalf. The permission and workflow controls in our Claude Code best-practices guide still apply.

Verification checklist

Use this acceptance test on the user's real OS, terminal, and assistive technology. It avoids modifying a project.

1. Confirm the executable. Run claude --version; require v2.1.181 or later and prefer v2.1.211 or later.
2. Confirm activation. Start claude --ax-screen-reader and listen for or inspect the startup confirmation. On current builds it should name flag.
3. Confirm labels and table linearization. Submit: Reply with a two-column Markdown table containing one row: Mode, ready. Verify the user and Claude labels are announced, and on v2.1.198+ the table reads as header-value sentences rather than a box grid.
4. Confirm menu control. Open a dismissible selection menu such as /theme. Verify that choices are numbered, the valid range is announced, an out-of-range number is rejected without exiting, and Escape cancels the menu.
5. Confirm caret tracking. Type a first line, use Ctrl+J to add a second line without submitting, and edit both lines. Use the screen reader's current-line command to check that focus follows the input caret, then clear the draft.
6. Confirm permission-mode feedback. On v2.1.210+, cycle once with Shift+Tab, verify a one-time announcement such as [plan mode on], then return to the user's original mode. Do not leave a more permissive mode selected by accident.
7. Confirm history navigation. Use the terminal's marker shortcut where supported; otherwise search scrollback for you: and move through at least two turns.
8. Confirm alerts. First prove the terminal bell works with printf '\a' outside Claude Code. Then verify an alert at the end of a harmless reply.
9. Confirm persistence. Relaunch through the intended environment variable or user setting and verify the startup line names that method.
10. Confirm rollback. Disable that method, relaunch, and verify the screen-reader confirmation is absent and the normal renderer returns.

Record the Claude Code version, OS, terminal and version, assistive technology and version, activation method, and result for each check. A short evidence log is more useful than “works on my machine.” Teams that use the test loop in our Claude Code QA app guide can add this matrix to the same release check.

Troubleshooting decision table

Team rollout checklist

• Inventory the combinations people actually use: OS, terminal, shell or PowerShell, screen reader or Braille software, and versions.
• Standardize on v2.1.211 or later, then record the exact tested build instead of saying “latest.”
• Let each user choose the flag, environment, or user setting. Keep the preference out of shared project configuration unless every collaborator has explicitly agreed to it.
• Run the verification checklist with the user who depends on the assistive technology; a sighted review of the plain transcript is not equivalent.
• Include permission prompts, long replies, tables, errors, multiline input, terminal search, bells, and rollback—not only a successful greeting.
• Treat claude attach and other alternate-screen workflows as a separate test because foreground success does not cover them.
• Document how to re-enable the terminal bell and how to remove every persistence mechanism.
• Keep a small issue template with Claude Code, OS, terminal, and assistive-technology versions plus a secret-free reproduction.
• Re-run acceptance checks after changing Claude Code, the terminal, the screen reader, shell profiles, or managed settings.

Privacy and known limitations

Screen reader mode changes terminal presentation, not Claude Code's data path. Anthropic's data-usage documentation says prompts and model outputs are sent over the network for inference, with retention depending on account type and preferences. Its application-data guide says local session transcripts and tool results under ~/.claude/projects/ are plaintext and subject to a 30-day cleanup by default. The separate prompt-history file at ~/.claude/history.jsonl persists until it is manually deleted. Terminal scrollback is another local copy. On a shared machine, review operating-system permissions, terminal history behavior, and the cleanupPeriodDays or CLAUDE_CODE_SKIP_PROMPT_HISTORY controls before handling sensitive material.

Do not paste credentials, private source, or a full transcript into a public accessibility issue. Anthropic asks reports to name the operating system, terminal, assistive technology, and versions; a minimal redacted reproduction is usually enough.

Current documented limitations remain:

• activation is opt-in rather than automatic when a screen reader starts;
• permission-mode changes are announced only when cycling with Shift+Tab;
• attached background sessions still use the alternate screen and lack native scrollback;
• costs are announced in the exit summary rather than after each turn;
• claude -p non-interactive mode is unchanged because it already writes plain text;
• the docs name VoiceOver and NVDA as examples but do not certify every assistive technology or terminal combination.

A rollout can therefore accept foreground use while keeping background sessions and unlisted assistive technologies marked as unverified.

Official sources

• ClaudeDevs screen reader announcement, activation follow-up, and documentation link
• Use Claude Code with a screen reader
• Claude Code settings and environment variables
• CLI reference and terminal configuration
• Installation and updates and installation troubleshooting
• Claude Code changelog
• Data usage and local application data
• Claude Code issue tracker