Use Claude Code with a screen reader changedaccessibility
Nearest release: v2.1.234, published 8 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+48added
Lines−52removed
From line
2
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits12to this page, all time
## Accessibility settings ## Accessibility settings beyond screen reader mode ## Related resources
The whole hunk
from line 2, old and new numbered
/
from line 2
22
33> Set up Claude Code for screen readers such as VoiceOver and NVDA, plus settings for screen magnifiers, reduced motion, and colorblind-friendly themes.
44
5Claude Code has a screen reader mode that replaces its visual terminal interface with plain, linear text. Instead of boxes, progress animations, and in-place redraws, the mode prints labeled lines that a screen reader such as VoiceOver or NVDA reads in order, so you can hold a full conversation, approve tool permissions, and review output end to end.
5Claude Code has a screen reader mode that replaces its visual terminal interface with plain, linear text. Instead of boxes, progress animations, and in-place redraws, Claude Code prints labeled lines that a screen reader such as VoiceOver or NVDA reads in order. You can hold a full conversation, approve tool permissions, and review output end to end.
66
7Screen reader mode is opt-in. If you use a screen magnifier, reduced motion, or a colorblind-friendly theme instead of a screen reader, see [Accessibility settings beyond screen reader mode](#accessibility-settings-beyond-screen-reader-mode).
7Screen reader mode is opt-in. If you use a screen magnifier, reduced motion, or a colorblind-friendly theme instead of a screen reader, set `CLAUDE_CODE_ACCESSIBILITY`, `prefersReducedMotion`, or `theme` from the [Accessibility settings](#accessibility-settings) table.
88
9<Note>
10 Screen reader mode requires Claude Code v2.1.181 or later. Earlier versions reject the `--ax-screen-reader` flag with `error: unknown option '--ax-screen-reader'`.
11</Note>
9Screen reader mode requires Claude Code v2.1.181 or later. Earlier versions reject the `--ax-screen-reader` flag with `error: unknown option '--ax-screen-reader'`.
1210
1311## Turn on screen reader mode
1412
from line 13
1513Pick the method that matches how often you use a screen reader:
1614
1715* For one session: run `claude --ax-screen-reader`.
18* For sessions started from one shell: set the `CLAUDE_AX_SCREEN_READER` environment variable to `1`. In Bash or Zsh, run `export CLAUDE_AX_SCREEN_READER=1`; in PowerShell, run `$env:CLAUDE_AX_SCREEN_READER = "1"`. Add the line to your shell profile to cover every shell.
19* For every session on the machine: add `"axScreenReader": true` to your user [settings file](/docs/en/settings). This covers any terminal, including the VS Code integrated terminal.
16* For sessions started from one shell: set the `CLAUDE_AX_SCREEN_READER` environment variable to `1`. In Bash or Zsh, run `export CLAUDE_AX_SCREEN_READER=1`. In PowerShell, run `$env:CLAUDE_AX_SCREEN_READER = "1"`. Add that line to your shell profile to keep it for future shells.
17* For every session on the machine: add `"axScreenReader": true` to your user [settings file](/docs/en/settings). The setting applies in any terminal, including the VS Code integrated terminal.
2018
21<Note>
22 The methods are listed in precedence order: the [`--ax-screen-reader`](/docs/en/cli-reference#cli-flags) flag overrides the [`CLAUDE_AX_SCREEN_READER`](/docs/en/env-vars) environment variable, which overrides the [`axScreenReader`](/docs/en/settings#available-settings) setting.
23</Note>
19If you combine methods, Claude Code applies the [`--ax-screen-reader`](/docs/en/cli-reference#cli-flags) flag over the [`CLAUDE_AX_SCREEN_READER`](/docs/en/env-vars#variables) environment variable, and the variable over the [`axScreenReader`](/docs/en/settings#available-settings) setting.
2420
2521If you use Claude Code over SSH, set the environment variable or setting on the remote machine where Claude Code runs.
2622
27When the mode is on, the first thing Claude Code prints is a confirmation line naming the method that turned it on: `[Screen Reader Mode: on via flag]`, `[Screen Reader Mode: on via env]`, or `[Screen Reader Mode: on via settings]`. The method-naming format requires Claude Code v2.1.206 or later. When Claude Code relaunches itself, for example to finish installing an update, the new process inherits the mode through the `CLAUDE_AX_SCREEN_READER` environment variable, so its confirmation line reads `[Screen Reader Mode: on via env]` regardless of which method you used.
28Earlier versions print `[Accessible screen reader mode: on]`.
23The first line Claude Code prints confirms the mode: `[Screen Reader Mode: on via flag]`, `[Screen Reader Mode: on via env]`, or `[Screen Reader Mode: on via settings]`.
2924
30After printing the confirmation line, Claude Code holds the rest of the interface back for three seconds so your screen reader can finish speaking the line, then renders the first prompt. Press any key to end the hold early. To change the hold's length, set the `CLAUDE_AX_STARTUP_QUIET_MS` environment variable to a number of milliseconds. The default is `3000`; set it to `0` to skip the hold. Claude Code caps the hold at `600000` milliseconds, 10 minutes. Requires Claude Code v2.1.217 or later.
31
3225## Turn off screen reader mode
3326
34Reverse whichever method turned the mode on: start without the flag, unset the environment variable, or set `axScreenReader` to `false`. Setting `CLAUDE_AX_SCREEN_READER=0` keeps the mode off even when the setting is `true`.
27Reverse whichever method turned the mode on: start without the flag, unset the environment variable, or set `axScreenReader` to `false`. If you set `CLAUDE_AX_SCREEN_READER` to `0`, Claude Code keeps the mode off even when the setting is `true`.
3528
29## Accessibility settings
30
31The table lists each accessibility option, whether you set it as a flag, an environment variable, or a setting, and what it changes.
32
33| Option | Type | What it changes |
34| :--------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35| [`--ax-screen-reader`](/docs/en/cli-reference#cli-flags) | Flag | Screen reader mode for one session. |
36| [`CLAUDE_AX_SCREEN_READER`](/docs/en/env-vars#variables) | Environment variable | Screen reader mode for sessions started from the shell where you set it. |
37| [`axScreenReader`](/docs/en/settings#available-settings) | Setting | Screen reader mode for every session when `true`. |
38| [`CLAUDE_AX_STARTUP_QUIET_MS`](/docs/en/env-vars#variables) | Environment variable | How long Claude Code waits after the confirmation line before it draws the first prompt in screen reader mode. Requires Claude Code v2.1.217 or later. |
39| [`CLAUDE_AX_PREPARK_MS`](/docs/en/env-vars#variables) | Environment variable | How long Claude Code waits, with the cursor at the start of the line, before it writes a new or changed line in screen reader mode. Requires Claude Code v2.1.233 or later. |
40| [`CLAUDE_CODE_ACCESSIBILITY`](/docs/en/env-vars#variables) | Environment variable | A terminal cursor that stays visible for screen magnifiers such as macOS Zoom when you set it to `1`. The cursor follows the input caret and, on Claude Code v2.1.218 or later, the highlighted row in menus and panels such as `/config` and `/plugin`. |
41| [`prefersReducedMotion`](/docs/en/settings#available-settings) | Setting | Reduced or no spinners, shimmer, and other animations when `true`. |
42| [`theme`](/docs/en/settings#available-settings) | Setting | The interface colors, including the colorblind-friendly `dark-daltonized` and `light-daltonized` themes. You can also pick one with [`/theme`](/docs/en/commands#all-commands). |
43| [`preferredNotifChannel`](/docs/en/settings#available-settings) | Setting | With the value `"terminal_bell"`, a terminal bell outside screen reader mode when Claude is waiting on you. |
44
3645## What your screen reader hears
3746
3847In screen reader mode, Claude Code writes flat text:
3948
40* no box-drawing characters for the interface chrome
41* no color-only cues
42* no redraws of content that hasn't changed; progress spinners render as static text
43* tables in Claude's replies read as `Header: value` sentences instead of a box-character grid. Requires Claude Code v2.1.198 or later; earlier versions draw tables as grids even in screen reader mode.
49* No box-drawing characters for the interface chrome
50* No color-only cues
51* No redraws of content that hasn't changed. Progress spinners render as static text
52* Tables in Claude's replies read as `Header: value` sentences instead of a box-character grid
4453
45Output accumulates in your terminal's scrollback, so you can re-read earlier turns with your screen reader's review commands or your terminal's search.
54Claude Code leaves everything it prints in your terminal's scrollback, so you can re-read earlier turns with your screen reader's review commands or your terminal's search. Claude Code ignores the [`tui` setting](/docs/en/settings#available-settings) in screen reader mode. Apart from the attached background sessions listed under [Known limitations](#known-limitations), it prints scrolling text instead of [fullscreen rendering](/docs/en/fullscreen).
4655
47Screen reader mode renders as plain scrolling text, even if you've turned on [fullscreen rendering](/docs/en/fullscreen) with the [`tui` setting](/docs/en/settings#available-settings); the setting has no effect while the mode is active. Attached background sessions still render fullscreen; see [Known limitations](#known-limitations).
56Claude Code also waits at two points so your screen reader can keep up:
4857
49Each message in the transcript starts with a label your screen reader announces, naming what it is: your messages, Claude's replies, tool activity, errors, and prompts. The labels are also searchable, so you can jump between sections of the transcript by searching your terminal's scrollback:
58* After Claude Code prints the confirmation line, it waits 3 seconds before it draws the prompt, so your screen reader can finish the line. Press any key to end the wait. To change the length of the wait, set [`CLAUDE_AX_STARTUP_QUIET_MS`](/docs/en/env-vars#variables).
59* Before Claude Code writes a new or changed line, such as a hint or more of Claude's reply, it moves the cursor to the start of the line and waits 50 milliseconds. Your screen reader then reads the line from its first character. Characters you type or delete at the end of the input line appear immediately. To change the length of the wait, set [`CLAUDE_AX_PREPARK_MS`](/docs/en/env-vars#variables).
5060
61Each message in the transcript starts with a label your screen reader announces, naming what it is: your messages, Claude's replies and thinking, tool activity, errors and warnings, and prompts. The labels are also searchable, so you can jump between sections of the transcript by searching your terminal's scrollback:
62
5163| Label | Meaning |
5264| :--------------------- | :---------------------------------------------------------------------------------------- |
5365| `you:` | Your messages |
5466| `claude:` | Claude's replies |
67| `thinking:` | Claude's thinking |
5568| `tool:` | Tool activity, such as a file edit or a command run |
5669| `tool error:` | A tool that failed |
5770| `error:` | An error in the conversation, such as a failed API request |
71| `warning:` | A warning from Claude Code, such as a switch to a fallback model |
5872| `Permission Required:` | A permission prompt waiting for your answer |
5973| `Cost:` | The session cost summary when Claude Code exits, if your account [shows costs](/docs/en/costs) |
6074
61The terminal cursor follows the input caret, so a screen reader's read-current-line command answers "where am I" with the prompt you're editing.
75Claude Code keeps the terminal cursor on the input caret, so your screen reader's read-current-line command reads the prompt you're editing.
6276
63As you type or press `Backspace` at the end of the input line, Claude Code writes only the characters that change, so your screen reader echoes just those characters. Deletions require Claude Code v2.1.222 or later and typing requires v2.1.219 or later; before those versions, each keystroke rewrote the line, so the screen reader re-read it.
77As you type at the end of the input line, or press `Backspace` there, Claude Code writes only the characters that change. Your screen reader echoes only those characters.
6478
65When you delete a word or a line in the input, Claude Code announces the deleted text. Requires Claude Code v2.1.218 or later. The announcement covers:
79When you delete a word or a line with one of the [text editing shortcuts](/docs/en/interactive-mode#text-editing), Claude Code announces the deleted text:
6680
6781* Deleting a word with `Ctrl+W`, `Option+Delete` on macOS, or `Ctrl+Backspace` on Windows
6882* Deleting to the start of the line with `Ctrl+U` or `Cmd+Backspace`
6983* Deleting to the end of the line with `Ctrl+K`
7084
71See the [text editing shortcuts](/docs/en/interactive-mode#text-editing) for what each key does.
85When you cycle [permission modes](/docs/en/permission-modes) with `Shift+Tab`, Claude Code announces the permission mode you land on, such as `[plan mode on]` or `[accept edits on]`. Claude Code prints the announcement once and doesn't repeat it on later redraws.
7286
73Cycling [permission modes](/docs/en/permission-modes) with `Shift+Tab` announces the mode you land on, such as `[plan mode on]` or `[accept edits on]`. Claude Code prints the announcement once and doesn't repeat it on later redraws. Requires Claude Code v2.1.210 or later.
74
7587### Jump between turns
7688
7789Claude Code emits OSC 133 shell-integration markers at turn boundaries, so your terminal's jump-to-previous-prompt key moves between turns without reading through the whole transcript:
from line 97
8597
8698## Answer menus and prompts
8799
88In screen reader mode, menus you'd normally navigate with the arrow keys, including permission prompts, become numbered lists. Each option is announced as a numbered line, followed by an `Enter selection` prompt that names the valid range. Type the number of the option you want and press Enter.
100In screen reader mode, menus you'd normally navigate with the arrow keys, including permission prompts, become numbered lists. Claude Code announces each option as a numbered line, then an `Enter selection` prompt that names the valid range. Type the number of the option you want and press Enter.
89101
90* To cancel a dismissible menu: press Escape. Its prompt ends with `or Escape to cancel`.
91* If you type a number that isn't on the list: Claude Code announces the valid range and lets you try again.
102* Press Escape to cancel a menu whose prompt ends with `or Escape to cancel`.
103* If you type a number that isn't on the list, Claude Code announces the valid range and lets you try again.
92104
105The [`/effort`](/docs/en/model-config#adjust-effort-level) selector, which is a slider outside screen reader mode, becomes the same kind of numbered list.
106
93107Yes-or-no prompts ask for a typed answer instead of a two-option menu. Answer `y` or `n` and press Enter. `yes` and `no` also work.
94108
95109## Hear when Claude Code needs you
from line 111
97111In screen reader mode, Claude Code rings the terminal bell when it needs your attention, so you don't have to keep checking the transcript. The bell rings when:
98112
99113* Claude finishes a reply
100* a permission prompt appears
101* a tool that ran longer than 5 seconds finishes
114* A prompt or dialog needs your answer, such as a permission prompt
115* A tool that ran longer than 5 seconds finishes
102116
103The bell is your terminal's standard alert. To silence it, change the bell setting in your terminal application. The bell doesn't require screen reader mode: outside the mode, set [`preferredNotifChannel`](/docs/en/settings#available-settings) to `"terminal_bell"` for similar alerts when Claude is waiting on you. See [Get a terminal bell or notification](/docs/en/terminal-config#get-a-terminal-bell-or-notification).
117The bell is your terminal's standard alert. To silence it, change the bell setting in your terminal application. Outside screen reader mode, set [`preferredNotifChannel`](/docs/en/settings#available-settings) to `"terminal_bell"` to get a [similar bell](/docs/en/terminal-config#get-a-terminal-bell-or-notification) when Claude is waiting on you.
104118
105## Accessibility settings beyond screen reader mode
106
107These options address accessibility needs outside of screen reader mode. All of them work alongside it.
108
109* The `CLAUDE_CODE_ACCESSIBILITY` [environment variable](/docs/en/env-vars) is for screen magnifiers. Set `CLAUDE_CODE_ACCESSIBILITY=1` to keep the native terminal cursor visible so that magnifiers, such as macOS Zoom, can track the cursor position. The cursor follows keyboard focus: the input caret while you type, and the highlighted row as you move through menus and panels, such as `/config` and `/plugin`, with the arrow keys. Row tracking in menus and panels requires Claude Code v2.1.218 or later.
110* The `prefersReducedMotion` [setting](/docs/en/settings#available-settings) reduces or disables spinners, shimmer, and other animations without changing the rest of the interface.
111* The `theme` [setting](/docs/en/settings#available-settings) selects the interface colors, including the colorblind-friendly `dark-daltonized` and `light-daltonized` themes.
112
113119## Known limitations
114120
115121Some behaviors aren't adapted for screen reader mode:
from line 129
123129## Report an issue
124130
125131If something doesn't work with your screen reader, magnifier, or terminal, open an issue on the [Claude Code issue tracker](https://github.com/anthropics/claude-code/issues) and mention your assistive technology in the title. Include your operating system, terminal application, and assistive technology name and version in the report.
126
127## Related resources
128
129These pages hold the full reference entries and related setup for what this page covers:
130
131* [Settings](/docs/en/settings#available-settings): the `axScreenReader`, `prefersReducedMotion`, `theme`, and `preferredNotifChannel` entries
132* [Environment variables](/docs/en/env-vars): the `CLAUDE_AX_SCREEN_READER` and `CLAUDE_CODE_ACCESSIBILITY` entries
133* [CLI reference](/docs/en/cli-reference#cli-flags): the `--ax-screen-reader` flag
134* [Terminal configuration](/docs/en/terminal-config): bells, notifications, and themes outside screen reader mode
135* [Non-interactive mode](/docs/en/headless): scripted `claude -p` runs, which write plain text without screen reader mode
136132
No line in this hunk matches that.