Software Development
Claude Code Accessibility: Screen Readers and Beyond
August 202611 min read
Three ways, in order of precedence: the --ax-screen-reader flag for one session, the CLAUDE_AX_SCREEN_READER environment variable set to 1 for one shell, or axScreenReader set to true in your user settings for every session. The first line printed confirms which method took effect. Over SSH, set it on the remote machine where Claude Code runs.
It replaces the visual terminal interface with plain linear text: no box-drawing characters, no colour-only cues, no redraws of unchanged content, and tables read as header-and-value sentences. Every message opens with a searchable label such as you, claude, tool or Permission Required, and menus become numbered lists you answer by typing a number.
No. Screen reader mode is opt-in and does not turn on automatically when a screen reader is running. That is listed as a known limitation. You set it with the flag, environment variable or setting, and the confirmation line at startup tells you which one applied.
Yes, three. CLAUDE_CODE_ACCESSIBILITY keeps a terminal cursor visible for magnifiers and makes it follow the highlighted row in menus. prefersReducedMotion reduces or removes spinners and shimmer. The dark-daltonized and light-daltonized themes are colourblind-friendly and usable as a base for a custom theme.
Two ways. Claude Code emits OSC 133 markers at turn boundaries, so your terminal's jump-to-previous-prompt key moves between turns — Cmd+Shift+Up in iTerm2, Ctrl or Cmd+Up in the VS Code terminal. Where those markers are unsupported, search the scrollback for the message labels, which are ordinary searchable text.
Key Takeaway
Claude Code has an opt-in screen reader mode that replaces its visual terminal interface with plain, linear text. Instead of box-drawing characters, progress animations and in-place redraws, it prints labelled lines that VoiceOver or NVDA read in order. Menus become numbered lists you answer by typing a number.
Terminal user interfaces are hostile to screen readers by construction. Boxes drawn from line characters, spinners that redraw the same cell forty times a second, tables rendered as a grid of pipes — every one of those is a design that assumes eyes. A screen reader given that output reads punctuation.
Claude Code's answer is a separate rendering mode rather than a set of tweaks, and it is worth understanding even if you do not use a screen reader, because three of the settings around it help with magnifiers, motion sensitivity and colour vision without touching the mode at all. This post covers turning it on, what changes, how menus work, the terminal integration that makes navigation practical, and the limitations stated honestly.
The mode is opt-in and does not turn on automatically when a screen reader is running. Pick the method that matches how often you need it — a flag for one session, an environment variable for one shell, a setting for the machine — and note that the variable set to zero keeps the mode off even when the setting says otherwise, which is the escape hatch when a machine-wide setting is inconvenient for one task.
# Three ways in, highest precedence first.
claude --ax-screen-reader # one session
export CLAUDE_AX_SCREEN_READER=1 # sessions from this shell
{ "axScreenReader": true } # every session on the machine
# The flag beats the variable, and the variable beats the
# setting. Setting the variable to 0 keeps the mode OFF even
# when the setting says true.
#
# Over SSH, set it on the REMOTE machine where Claude Code runs.
#
# The first line printed confirms which one won:
# [Screen Reader Mode: on via flag]
# [Screen Reader Mode: on via env]
# [Screen Reader Mode: on via settings]
# Other accessibility options, none of which need this mode:
CLAUDE_CODE_ACCESSIBILITY=1 # cursor stays visible for
# magnifiers, and follows the
# highlighted row in menus
{ "prefersReducedMotion": true } # no spinners or shimmer
{ "theme": "dark-daltonized" } # colourblind-friendlyOver SSH, set the variable or setting on the remote machine where Claude Code actually runs, not on the machine you are typing on. That is the single most common reason the mode appears not to work — and the confirmation line printed at startup is how you check, because it names which of the three methods took effect.
The mode is not a smaller version of the visual interface. It is a different output format built around being read aloud in order:
Every message in the transcript opens with a label naming what it is. That makes the reader's job unambiguous, and it has a second benefit that is easy to miss: the labels are ordinary searchable text, so your terminal's find becomes a way to jump between sections of a long transcript.
# Every message opens with a label your screen reader
# announces — and the labels are SEARCHABLE, so your
# terminal's find jumps between sections of the transcript.
you: your messages
claude: Claude's replies
thinking: Claude's thinking
tool: a file edit, a command run
tool error: a tool that failed
error: a failed API request
warning: a switch to a fallback model, and similar
Permission Required: waiting for your answer
Cost: the session summary printed at exit
# Two deliberate pauses let the reader keep up:
# 3s after the confirmation line, before the first prompt.
# Press any key to skip. CLAUDE_AX_STARTUP_QUIET_MS
# 50ms before writing a new or changed line, with the cursor
# parked at the start of it, so the reader reads from
# character one. CLAUDE_AX_PREPARK_MSClaude Code emits shell-integration markers at turn boundaries, so your terminal's jump-to-previous-prompt key moves between turns without reading through everything in between. iTerm2 and the VS Code terminal both have one bound by default; Windows Terminal needs you to bind its scroll-to-mark action yourself. macOS Terminal ignores the markers and they are not emitted in WezTerm — in those, search the scrollback for the message label instead.
Anything you would normally navigate with arrow keys becomes a numbered list. Claude Code announces each option as a numbered line, then a prompt naming the valid range, and you type the number and press Enter. Type a number that is not on the list and it announces the valid range and lets you try again — including for permission prompts, which are the interaction that matters most.
Two related adaptations are worth knowing. The effort selector, which is a slider in the visual interface, becomes the same kind of numbered list. And yes-or-no prompts ask for a typed answer rather than presenting a two-option menu, accepting either the single letter or the whole word.
Three of the accessibility options are independent of screen reader mode, and they are the ones most likely to help the most people. If you use a magnifier, are sensitive to motion, or have a colour vision difference, none of these require adopting a different rendering mode.
Independent accessibility settings:
| Setting | What it does |
|---|---|
| The accessibility environment variable | Keeps a terminal cursor visible for magnifiers such as macOS Zoom, following the input caret and the highlighted row in menus and panels |
| The reduced-motion setting | Reduces or removes spinners, shimmer and other animation |
| The daltonized themes | Colourblind-friendly palettes in both light and dark, usable as a base for a custom theme |
| The terminal-bell notification channel | An audible alert when Claude is waiting on you, outside screen reader mode |
In screen reader mode the terminal bell rings at the three moments that matter, so you do not have to keep checking the transcript:
Text editing announces what it removed rather than leaving you to infer it. Deleting a word, deleting to the start of the line and deleting to the end of the line each announce the deleted text. Typing and backspacing at the end of the input write only the characters that changed, so your reader echoes those rather than re-reading the whole line — which is the detail that makes editing a long prompt bearable.
The documentation is unusually honest about what is not adapted, and it is worth repeating rather than discovering. The mode does not turn on automatically when a screen reader is running. A permission mode changed by any route other than cycling with the keyboard is not announced. Costs are announced in the summary at exit rather than per turn.
One structural limitation is worth planning around: attaching to a background session enters the terminal's alternate screen, which has no native scrollback — the same behaviour as any attached session. Getting back out is an arrow key on an empty prompt, or the suspend chord if a dialog has focus. If your workflow leans on background agents, that is the one place the linear-text guarantee does not hold.
The thing worth taking from this even if you are not the audience: the accessible mode is not a degraded version of the interface, it is a different rendering of the same session, and several of its ideas are better. Labelled turns you can search, output that never redraws itself, tables that read as sentences — those are all improvements that happen to be necessary for one group and useful to everyone. If something does not work with your assistive technology, the issue tracker asks for your operating system, terminal and technology version, and that report is how the next version gets it right.
Sources & further reading