Skip to main content

Accessibility

Beginner

Claude Code runs in the terminal — a text UI, which is a good starting point for accessibility, but the default rendering leans on color, box-drawing glyphs, and spinners that screen readers and some motor setups handle poorly. As of July 2026 there's a dedicated screen reader mode plus settings for vim ergonomics and mouse/scroll behavior. This page collects the levers that make the CLI usable with assistive tech.

What you'll learn
  • How to turn on screen reader mode — three ways, and what each changes
  • What screen reader mode actually does to the transcript, tables, and permission prompts
  • How to remap vim insert-mode keys (jj → Escape) to reduce hand strain
  • How to control or disable mouse clicks and scroll acceleration in fullscreen
  • Where high-contrast themes live, and how to report an accessibility gap

Screen reader mode​

Screen reader mode swaps the decorative TUI for a plain-text rendering that assistive tech can read cleanly. Turn it on any of three ways — a one-off flag, an environment variable for every session, or a persistent setting.

Guided walkthrough1 of 3
  1. Launch with the flag: claude --ax-screen-reader. Nothing else changes — same session, plainer output.

Persistent screen reader mode (~/.claude/settings.json)

{
"axScreenReader": true
}

What it changes​

Pro tip
  • Plain-text rendering replaces the styled TUI so screen readers get clean, linear text.
  • Decorative glyphs are hidden from screen readers instead of being read out as noise.
  • Transcript symbols are announced as short labels rather than raw characters.
  • Nested tables are read as Header: value. lines — flattened into speakable rows.
  • Permission mode changes are announced aloud when you cycle modes with Shift+Tab.

That last one matters: cycling permission modes with Shift+Tab is a core Claude Code interaction (see Permissions), and screen reader mode speaks the new mode aloud so you always know whether you're in plan, accept-edits, or auto mode without reading the status line.

Vim ergonomics: remap insert-mode keys​

If you use vim mode and reaching for Escape strains your hand, map a two-key insert-mode sequence to it instead. The vimInsertModeRemaps setting turns sequences like jj into Escape, so you never leave the home row.

Map jj to Escape in vim mode (settings.json)

{
"editorMode": "vim",
"vimInsertModeRemaps": {
  "jj": "Escape"
}
}
Watch out
  • The remap only fires in insert mode, so typing jj as literal text needs a brief pause between keys — pick a sequence you rarely type fast (jj and kj are common choices).
  • editorMode: vim enables vim keybindings; vimInsertModeRemaps only takes effect while vim mode is on.

Mouse and scroll controls​

Fullscreen menus now accept mouse clicks — including multi-select menus and the "Other" input rows — which helps if keyboard-only navigation is painful. Two settings tune pointer behavior for motion sensitivity or precision:

SettingWhat it does
CLAUDE_CODE_DISABLE_MOUSE_CLICKSDisables mouse click, drag, and hover while keeping wheel scroll — useful if stray clicks disrupt you.
wheelScrollAccelerationEnabledSet to false to turn off mouse-wheel scroll acceleration in fullscreen, for steadier, predictable scrolling.

Steadier scrolling, no accidental clicks (settings.json)

{
"wheelScrollAccelerationEnabled": false,
"env": {
  "CLAUDE_CODE_DISABLE_MOUSE_CLICKS": "1"
}
}

Contrast and themes​

For low-vision users, terminal contrast is the first lever. Claude Code ships light and dark themes and supports custom themes you build from /theme or ship in a plugin — so you can dial in a high-contrast palette that meets your needs. See Settings for where theme choice is stored, and Output Styles if you also want plainer, less-decorated prose (the Explanatory and Learning styles are more verbose, not less — for terse output stay on Default).

:::tip Beyond the CLI Screen reader mode covers the terminal. For hands-free interaction with Claude more broadly, Voice Mode in the app lets you talk and listen, and the Accessibility playbook covers using Claude itself as an assistive tool — simplifying text, building checklists, and adapting information to how you read. :::

Check yourself

0/3
  1. Which of these turns on screen reader mode for every session automatically?
  2. In screen reader mode, how are nested tables read?
  3. What does vimInsertModeRemaps let you do?
Pro tip
  • Screen reader mode: --ax-screen-reader flag (once), CLAUDE_AX_SCREEN_READER=1 (per shell), or axScreenReader: true (persistent).
  • It plain-texts the transcript, hides decorative glyphs, flattens tables, and speaks permission-mode changes on Shift+Tab.
  • vimInsertModeRemaps eases hand strain; CLAUDE_CODE_DISABLE_MOUSE_CLICKS and wheelScrollAccelerationEnabled tune pointer behavior.
  • Custom themes give you high-contrast palettes; Voice Mode and the Accessibility playbook cover the rest.

Next​