Skip to main content
Claude 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. Screen 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 table. 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'.

​
Turn on screen reader mode

Pick the method that matches how often you use a screen reader:
  • For one session: run claude --ax-screen-reader.
  • 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.
  • For every session on the machine: add "axScreenReader": true to your user settings file. The setting applies in any terminal, including the VS Code integrated terminal.
If you combine methods, Claude Code applies the --ax-screen-reader flag over the CLAUDE_AX_SCREEN_READER environment variable, and the variable over the axScreenReader setting. If you use Claude Code over SSH, set the environment variable or setting on the remote machine where Claude Code runs. The 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].

​
Turn off screen reader mode

Reverse 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.

​
Accessibility settings

The table lists each accessibility option, whether you set it as a flag, an environment variable, or a setting, and what it changes.

​
What your screen reader hears

In screen reader mode, Claude Code writes flat text:
  • No box-drawing characters for the interface chrome
  • No color-only cues
  • No redraws of content that hasn’t changed. Progress spinners render as static text
  • Tables in Claude’s replies read as Header: value sentences instead of a box-character grid
Claude 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 in screen reader mode. Apart from the attached background sessions listed under Known limitations, it prints scrolling text instead of fullscreen rendering. Claude Code also waits at two points so your screen reader can keep up:
  • 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.
  • 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.
Each 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: Claude Code keeps the terminal cursor on the input caret, so your screen reader’s read-current-line command reads the prompt you’re editing. As 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. When you delete a word or a line with one of the text editing shortcuts, Claude Code announces the deleted text:
  • Deleting a word with Ctrl+W, Option+Delete on macOS, or Ctrl+Backspace on Windows
  • Deleting to the start of the line with Ctrl+U or Cmd+Backspace
  • Deleting to the end of the line with Ctrl+K
When you cycle 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.

​
Jump between turns

Claude 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:
  • iTerm2: Cmd+Shift+Up
  • VS Code terminal: Ctrl+Up on Windows, Cmd+Up on macOS
  • Windows Terminal: no key by default; bind the scrollToMark action in its settings
  • Kitty and Ghostty: check the terminal’s documentation for its jump-to-prompt key
macOS Terminal doesn’t act on the markers, and Claude Code doesn’t emit them in WezTerm. In those terminals, search the scrollback for the you: label instead.

​
Answer menus and prompts

In 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.
  • Press Escape to cancel a menu whose prompt ends with or Escape to cancel.
  • If you type a number that isn’t on the list, Claude Code announces the valid range and lets you try again.
The /effort selector, which is a slider outside screen reader mode, becomes the same kind of numbered list. Yes-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.

​
Hear when Claude Code needs you

In 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:
  • Claude finishes a reply
  • A prompt or dialog needs your answer, such as a permission prompt
  • A tool that ran longer than 5 seconds finishes
The bell is your terminal’s standard alert. To silence it, change the bell setting in your terminal application. Outside screen reader mode, set preferredNotifChannel to "terminal_bell" to get a similar bell when Claude is waiting on you.

​
Known limitations

Some behaviors aren’t adapted for screen reader mode:
  • Screen reader mode doesn’t turn on automatically when a screen reader is running.
  • Claude Code doesn’t announce a permission mode change made in any way other than cycling with Shift+Tab, such as entering plan mode from a command.
  • Attaching to a background session with claude attach or from agent view enters the terminal’s alternate screen, which has no native scrollback. This is the same behavior as other attached sessions. To get back out, press Left Arrow on an empty prompt, or Ctrl+Z if a dialog has focus.
  • Claude Code announces costs in the summary it prints at exit, not per turn.
  • Screen reader mode doesn’t change non-interactive mode with the -p flag. Non-interactive mode already writes plain text and remains an alternative for scripting.

​
Report an issue

If something doesn’t work with your screen reader, magnifier, or terminal, open an issue on the Claude Code issue tracker and mention your assistive technology in the title. Include your operating system, terminal application, and assistive technology name and version in the report.