Terminal Access for NVDA

Terminal Access adds keyboard-driven review navigation, search, bookmarks, and audio cues to 30 Windows terminal applications, including Windows Terminal, PowerShell, Command Prompt, WSL, and popular third-party emulators. It gives you line, word, and character navigation through terminal output without moving the cursor, so you can read command results the way you read a document.

Open this guide any time from inside a terminal by pressing NVDA+Shift+F1.

Table of Contents

1. Getting Started
2. Command Layer
3. Table Mode
4. Bookmarks
5. Error and Warning Detection
6. Gesture Conflict Detection
7. Application Profiles
8. Third-Party Terminal Support
9. Window Definitions
10. Unicode and CJK Text
11. Performance
12. AI CLI Support
13. Settings
14. Troubleshooting
15. Getting Help

Getting Started

Installation

1. Download the latest .nvda-addon file from the Releases page.
2. Press Enter on the downloaded file.
3. Confirm the prompt.
4. Restart NVDA.

Terminal Access requires Windows 10 or 11 and NVDA 2025.1 or later.

First Steps

Open any supported terminal. When Terminal Access recognizes it, you hear: "Terminal Access support active. Press NVDA+shift+f1 for help."

You read terminal output in two ways:

• Direct gestures: NVDA modifier combinations such as NVDA+I to read the current line. These work at any time inside a terminal.
• Command layer: Press NVDA+apostrophe to enter a mode where every command is a single key press. You hear "Terminal commands" and a high tone. Press Escape to leave.

The command layer is faster for a sequence of commands and avoids clashes with other add-ons. Both routes run the same commands, and you can remap every gesture in NVDA's Input Gestures dialog under "Terminal Access".

Essential Reading Commands

These few commands cover most reading. The first column is the key inside the command layer; the second is the equivalent direct gesture.

The full reference for every command is in the next section.

Command Layer

The command layer is a modal input mode that runs Terminal Access commands with single-key presses instead of multi-key NVDA modifier combinations. This avoids conflicts with other NVDA add-ons and makes commands faster to type.

Entering and Exiting

The layer stays active until you exit. Each command keeps you in the layer so you can chain commands. The layer exits on its own when focus leaves the terminal.

Command Reference

While in the command layer, these keys are active:

Navigation

Information and Reading

Selection and Copying

Window Management

Configuration

Bookmarks

Tabs

Search and URL List

The search dialog has a text box plus two options: Case sensitive (match letter case exactly) and Regular expression (treat the text as a Python regular expression). Both remember their setting for the next search in the session. If a regular expression is invalid, you hear a short message and the search is not run.

Search opens a results dialog listing every matching line. Activating a result (Enter or the Activate button) closes the dialog and places the review cursor at the beginning of the matched line, the same way a bookmark jump does, so review-current-line reads the match. After the dialog closes, F3 and Shift+F3 continue through the remaining matches, announcing each match's position as "N of M" and saying "Wrapped" when navigation loops back to the start. If a search finds nothing, close fuzzy matches (one typo away) are offered instead.

Search results are taken at the moment you search. If the program then prints more output, the next find-next or find-previous re-runs the search against the current buffer so the results stay accurate, keeping your place on the same matched line where possible. Results are remembered per terminal window for the current NVDA session; they are not saved across an NVDA restart.

Table Mode

Help and Settings

Copy Mode Within the Layer

When you press V in the command layer, you enter copy mode. The keys L (copy line), S (copy screen), and Escape (cancel) temporarily override their layer bindings. When copy mode exits, those bindings are restored.

Customizing Gestures

All Terminal Access commands, both layer and direct, are registered under the "Terminal Access" category in NVDA's Input Gestures dialog. You can remap any gesture.

URL List

Press E in the command layer (or NVDA+Alt+U directly) to scan the terminal buffer for URLs. An interactive dialog opens with:

Supported URL types: HTTP/HTTPS, FTP, www-prefixed, and OSC 8 terminal hyperlinks. Duplicate URLs are removed automatically.

Security note: URLs with file://, javascript:, or other non-web schemes are detected and listed but cannot be opened from the dialog. Attempting to open one produces the spoken message "Cannot open this URL type for security reasons." This stops malicious terminal output from tricking you into launching dangerous local resources.

Table Mode

Terminal programs often print tabular output such as docker ps, kubectl get pods, ls -l, psql result grids, and Markdown pipe tables. Read as plain lines, these become long run-on strings where a value is hard to match to its column. Table mode reads the output column by column and announces the header for each cell, so you always know which column you are in.

Entering and Exiting

Move the review cursor onto any line of the table, then press G in the command layer (or NVDA+Alt+G directly). If a table is detected at that position, table mode activates and the arrow keys navigate cells. If no table is found, you hear "No table at this position".

Press Escape or toggle the command again to leave table mode. Table mode also exits on its own when focus leaves the terminal.

Navigating Cells

While table mode is active, these keys navigate the detected table:

Each cell is announced with its column header followed by the cell value, so you can move down a column and compare values without losing track of what they mean.

Supported Table Shapes

Table mode recognizes two shapes:

Column Detection Is Heuristic (Experimental)

Table mode's column detection is heuristic. It infers where columns begin and end from the alignment of spaces and pipe characters in the visible text, because terminal output carries no structural markup describing its columns. This works well for the common tools listed above, but unusual spacing, wrapped lines, cells that contain multiple spaces, or wide (CJK) characters can place a column boundary in the wrong spot.

This behavior will be refined in future updates as we gather testing results and user reports of tables that are not detected or split correctly. If you hit a table that reads incorrectly, please report it with a sample of the output so the detection can be improved.

Bookmarks

Bookmarks let you save and revisit specific lines in the terminal buffer.

Setting Bookmarks

Press Shift+0 through Shift+9 in the command layer (or NVDA+Alt+0 through NVDA+Alt+9 directly) to set a bookmark at the current line. The line's text is captured as a label so you can identify it later.

Jumping to Bookmarks

Press 0-9 in the command layer (or Alt+0 through Alt+9 directly) to jump to that bookmark.

Bookmark List Dialog

Press B in the command layer (or NVDA+Shift+B directly) to open an interactive list. The dialog shows two columns: bookmark number and line content. Press Enter to jump to the selected bookmark, or Delete to remove it.

Bookmarks are kept per terminal window and persist while that window is open, including when focus leaves and returns. Separate terminal windows keep their own bookmarks. Note that several tabs inside a single Windows Terminal window share one window, so they share the same bookmarks. Bookmarks are held for the current NVDA session only; they are not saved across an NVDA restart. Up to 50 bookmarks are kept per window; once that limit is reached, setting a new one announces "Bookmark limit reached" until you delete one.

Because terminal output scrolls, a bookmark points at a line by its content. Jumping to a bookmark re-finds that line, which is reliable while the line is still in the buffer; if the line has scrolled out of the terminal's history, the jump may not land.

Error and Warning Detection

Terminal Access plays audio cues when you navigate to lines that contain errors or warnings. This helps you scan build output, test results, or log files by ear.

• Error lines produce a low-pitched tone.
• Warning lines produce a higher-pitched tone.

The detector recognizes common patterns from compilers, linters, and shell output, such as error:, ERROR, warning:, and WARN.

Audio Cue Settings

Configure these in NVDA menu > Preferences > Settings > Terminal Settings.

Gesture Scoping

Terminal Access gestures only activate inside supported terminals. Outside a terminal the gestures pass through to NVDA or other add-ons. Terminal detection uses an exact match on the process name.

Gesture Conflict Detection

Terminal Access detects when its keyboard shortcuts conflict with other installed NVDA add-ons. When it finds a conflict, it warns you so you can decide which binding to keep.

To resolve conflicts:

1. Open NVDA menu > Preferences > Settings > Terminal Settings.
2. In the "NVDA Gesture Conflicts" section, uncheck any gesture you want to disable.
3. Disabled direct gestures remain accessible through the command layer (NVDA+apostrophe).

The command layer and help gestures (NVDA+Shift+F1) cannot be disabled.

Application Profiles

Application profiles adjust Terminal Access settings based on the terminal application you are using. Each profile can customize punctuation levels, cursor tracking modes, and window regions for specialized behavior.

Understanding Profiles

Terminal Access ships with default profiles for popular applications:

• vim/nvim: Punctuation MOST (for code symbols), cursor tracking WINDOW mode, silent zones for the status line and command line.
• tmux: Cursor tracking STANDARD mode, silent zone for the status bar.
• htop: Repeated symbols disabled (progress bars repeat characters), window regions for the header (lines 1-4) and process list (lines 5+).
• less/more: Quiet mode enabled, key echo disabled.
• git: Punctuation MOST (symbols in diffs), repeated symbols disabled.
• nano: Cursor tracking STANDARD mode, silent zones for the status and shortcut bars.
• irssi: Punctuation SOME, line pause disabled for fast chat reading, silent zone for the status bar.
• WSL: Punctuation MOST (code-friendly for Linux commands and paths), cursor tracking STANDARD mode, repeated symbols off.

Managing Profiles

View, export, import, and delete profiles from NVDA menu > Preferences > Settings > Terminal Settings > Application Profiles. The "Installed profiles" dropdown lists default profiles first, then custom profiles alphabetically.

• Export: Select a profile and click "Export..." to save it as a JSON file with all settings and window definitions.
• Import: Click "Import..." and choose a profile JSON file. A profile with the same name is replaced.
• Delete: Select a custom profile and click "Delete Profile". Default profiles (vim, tmux, htop, less, git, nano, irssi) cannot be deleted.

Profile Setting Overrides

When a profile is active, its settings override the global Terminal Access settings. For example, if the less profile sets key echo off, key echo is disabled while less runs, regardless of the global setting.

If you toggle a setting such as quiet mode while a profile is active, the change is saved to that profile's overrides rather than the global settings. When you switch to a different application, the global settings return.

Creating Custom Profiles

Create a custom profile by exporting an existing one as a template, editing the JSON, and importing it back:

{
  "appName": "myapp",
  "displayName": "My Application",
  "punctuationLevel": 2,
  "cursorTrackingMode": 1,
  "quietMode": false,
  "keyEcho": true,
  "linePause": true,
  "repeatedSymbols": true,
  "windows": [
    {
      "name": "status",
      "top": 9999,
      "bottom": 9999,
      "left": 1,
      "right": 9999,
      "mode": "silent",
      "enabled": true
    }
  ]
}

Third-Party Terminal Support

Terminal Access supports 30 terminals: the 5 built-in Windows terminals, WSL, and 24 third-party emulators. It detects them automatically when you switch to them, and each has a default profile tuned for common use.

Built-in Windows Terminals

Windows Terminal, cmd (Command Prompt), powershell (Windows PowerShell), pwsh (PowerShell Core), and conhost (Console Host).

Third-Party Terminal Emulators

Cmder, ConEmu, mintty (Git Bash and Cygwin), PuTTY and KiTTY, Terminus, Hyper, Alacritty, WezTerm, Tabby, FluentTerminal, Ghostty, Rio, Wave Terminal, Contour, Cool Retro Term, MobaXterm, SecureCRT, Tera Term, mRemoteNG, and Royal TS.

Default Profiles by Category

All Terminal Access features work with third-party terminals: navigation, selection, cursor tracking, punctuation levels, and window definitions. To customize a terminal, use it, open NVDA Settings > Terminal Access, adjust settings, and export the profile for backup or sharing.

Window Definitions

Window definitions mark regions of the terminal screen with different speech behaviors. This helps with applications that have status bars, command areas, or split panes.

Basics

Each window definition has a name, coordinates (top, bottom, left, right), a mode, and an enabled flag.

Coordinates are 1-based, so row 1, column 1 is the top-left. The value 9999 means "last row or column".

Window Modes

Example: Vim Status Line

[
  {
    "name": "editor",
    "top": 1,
    "bottom": 9998,
    "left": 1,
    "right": 9999,
    "mode": "announce"
  },
  {
    "name": "status",
    "top": 9999,
    "bottom": 9999,
    "left": 1,
    "right": 9999,
    "mode": "silent"
  }
]

This reads all lines except the last (the editor region) normally and silences the last line (the status bar). Common uses include silencing status bars, defining tmux or screen panes, handling htop headers, and monitoring command input regions.

Unicode and CJK Text

Terminal Access handles double-width characters, right-to-left text, and complex emoji sequences.

CJK Characters

Chinese, Japanese, and Korean characters count as 2 columns, so column-based operations line up correctly. Zero-width combining marks are handled properly.

Hello世界   # "Hello" = 5 columns, "世界" = 4 columns, total = 9 columns

Right-to-Left Text

Terminal Access detects Arabic and Hebrew by character range and applies the Unicode bidirectional algorithm (UAX #9), including Arabic contextual reshaping and mixed RTL/LTR text.

For full RTL support, install the optional libraries:

pip install python-bidi arabic-reshaper

Without them, Terminal Access falls back to basic Unicode support.

Emoji

Terminal Access handles zero-width joiner sequences (family and profession emoji), skin tone modifiers, variation selectors, and flag sequences. Emoji are typically 2 columns wide.

For full emoji support, install the optional library:

pip install emoji

Performance

Terminal Access includes optimizations for large terminal buffers.

• Position caching: Position calculations are cached for up to 100 positions with a 1-second timeout, and invalidated on content changes, resize, or terminal switch. A calculation that is O(n) on first access becomes O(1) when cached.
• Incremental tracking: Small cursor movements (within 10 positions) are 10 to 20 times faster than a full calculation, with automatic fallback for large jumps.
• Background processing: Selections over 100 rows run in a background thread with a progress dialog and cancellation support.
• Pure Python: The add-on contains no compiled components. Earlier 2.0.0 betas bundled a native library and helper process for terminal reads; both were removed after field testing showed the in-process Python reads are faster and more reliable (the helper's reads hung for seconds on some terminals, and NVDA's own watchdog can recover a slow in-process read). Being pure Python, the add-on also runs on ARM64 versions of Windows without a separate build.

AI CLI Support

Terminal Access detects AI command-line tools and adds navigation for conversational workflows. Supported tools: Claude, Aider, ChatGPT CLI, GitHub Copilot CLI, Gemini CLI, OpenAI Codex CLI, and Ollama.

Experimental: turn and code-block detection is heuristic. It infers boundaries from each tool's prompt markers, so a tool with unusual output can split turns in the wrong place or miss a code block. If a conversation reads incorrectly, please report it with a sample so the detection can be improved.

Turn Navigation

Terminal Access splits the buffer into turns based on the role markers each AI CLI uses (user prompts and assistant responses).

When you land on a turn, Terminal Access announces the role (user or assistant) and the first line. If no more turns exist in that direction, you hear "No more turns."

Code Block Navigation

Terminal Access scans for fenced code blocks (triple backtick delimiters) and tracks the language, start line, end line, and content of each.

The explain command gives a brief offline explanation of the block. It is gated by the "Allow Code Explain" privacy setting, which is off by default.

Streaming Delta

Press NVDA+Shift+D to hear only what changed since the last check while an AI assistant is streaming its response. Terminal Access diffs the current buffer against a stored snapshot to find the new content.

Scoped Search

Press Ctrl+F in the command layer to search within the current AI turn only. Standard search (F in the command layer) still searches the full buffer.

AI Error Detection

Terminal Access recognizes AI-specific error patterns in addition to standard compiler and shell errors.

Rate limit and token limit errors produce a pulsing low tone (two quick 220 Hz beeps). Other API errors produce a single low tone.

Verbosity Level

The verbosity level controls how much optional context Terminal Access speaks. Press Shift+V in the command layer (or NVDA+Shift+V) to cycle through the levels, or set it in NVDA menu > Preferences > Settings > Terminal Settings.

Privacy Settings

Two settings control AI features that send terminal content to an external service. Both are off by default.

When you invoke a privacy-gated feature while it is disabled, Terminal Access explains that the feature is off and how to enable it. To enable, open NVDA Settings > Terminal Access > Privacy and check the setting.

Settings

Open settings from NVDA menu > Preferences > Settings > Terminal Settings.

The settings panel also has a "NVDA Gesture Conflicts" section for disabling conflicting gestures and an "Application Profiles" section for managing profiles.

Key Echo and NVDA's Typing Echo

NVDA has two typing-echo settings of its own in NVDA menu > Preferences > Settings > Keyboard: "Speak typed characters" and "Speak typed words". Terminal Access's Key Echo and those settings all announce typing, but they are not the same feature, and only one echoes at a time:

• When both of NVDA's typing-echo settings are off (recommended for terminal work), Terminal Access does the echo inside terminals. You get symbol names at your chosen punctuation level, repeated symbols condensed ("dash 4 times"), and per-application profile control: profiles for single-key programs such as less, lazygit, btop, and Claude turn echo off automatically so shortcuts do not chatter.
• When either of NVDA's typing-echo settings is on, NVDA echoes typing itself and Terminal Access steps aside. This matters especially for "Speak typed words": NVDA builds each spoken word from the individual keystrokes it sees, so if Terminal Access also echoed each character it would speak over the words. With NVDA's setting on, the add-on's Key Echo and any per-profile echo overrides have no effect, and you lose symbol condensing and the automatic per-application behavior.

In short: for the full terminal experience, leave both of NVDA's typing-echo settings off and use Terminal Access's Key Echo; turn on NVDA's settings only if you want the same echo in every application, in which case Terminal Access's Key Echo does nothing.

Troubleshooting

The add-on does not activate

• Confirm you are in a supported terminal.
• Check that the add-on is enabled in NVDA menu > Tools > Manage Add-ons.
• Restart NVDA.

Commands do not respond

• Try a different terminal application to see if the problem is terminal-specific.
• Check for keyboard shortcut conflicts in NVDA's Input Gestures dialog.
• Review the NVDA log (NVDA menu > Tools > View log).

Getting Help

• Press NVDA+Shift+F1 in any terminal to reopen this guide.
• Save an issue report: press Shift+I in the command layer (or NVDA+Alt+I directly) when a feature reads something wrong, for example table mode splitting a column in the wrong place or an AI turn detected at the wrong line. It saves a text file with your add-on and NVDA versions, the terminal, the active profile, and a buffer sample. Add a sentence about what you expected, then attach the file to a GitHub issue.
• Report issues on the GitHub issue tracker. Include your NVDA version, Terminal Access version, terminal application and version, steps to reproduce, and expected versus actual behavior.
• The frequently asked questions and version history are on GitHub.