# LIMA AI NVDA Add-on

> The complete LIMA AI NVDA Add-on documentation from https://docs.roscommon.systems/nvda-addon/, with every page in one file.

## LIMA AI NVDA Add-on

Source: https://docs.roscommon.systems/nvda-addon/

LIMA AI is an open-source NVDA add-on that brings on-demand AI screen description to NVDA users. It is a light companion to [LIMA Desktop](https://docs.roscommon.systems/lima/): it installs into NVDA and extends the NVDA experience with the same LIMA AI that powers the desktop app.

You control it from the keyboard with five NVDA gestures, no mouse required. The default gestures use the `NVDA+Alt` layer, so they never override a built-in NVDA command.

### What it does

- **Describe the screen:** press `NVDA+Alt+D` and NVDA speaks a brief, factual description of the active monitor: the main elements and any important visible text.
- **Describe the focused element:** press `NVDA+Alt+E` and NVDA tells you how the control you are on looks and what it does.
- **Click by description:** press `NVDA+Alt+C`, type what you want to do, such as *"click the Send button"*, and LIMA AI finds the control and clicks it.
- **Dynamic web narration:** press `NVDA+Alt+W` and the add-on briefly announces meaningful changes on the browser page you are reading, without interrupting your reading or repeating itself.
- **Check your credit usage:** press `NVDA+Alt+U` to hear how much of this month's AI credit you have used and when it resets.
- **Sign in with Google:** sign in once from NVDA's settings panel; the session is remembered, so you don't have to sign in again at every launch.
- **Speak in your language:** descriptions are spoken in the reply language of your choice (English, Tagalog, or Vietnamese), with a matching voice where one is available.

### What you need

| Requirement | Details |
| --- | --- |
| Windows | With NVDA 2023.1 or later installed |
| Internet connection | Required for the AI features |
| Google account | Used to sign in — no separate password to create |

### LIMA AI and LIMA Desktop

LIMA AI focuses on quick, on-demand answers while you work in NVDA. [LIMA Desktop](https://docs.roscommon.systems/lima/) is the full product — continuous narration, voice control, and computer automation.

| | LIMA AI add-on | LIMA Desktop |
|---|---|---|
| What it does | Describes your screen or the focused control on demand, clicks controls you describe, and narrates web changes | Reads, understands, and controls your whole computer |
| Where it runs | Inside NVDA | Windows desktop app |
| How you control it | Keyboard (NVDA gestures) | Voice and keyboard |
| Best for | Quick answers while you work in NVDA | Full hands-free computer use |
| Getting it | NVDA Add-on Store | [roscommon.systems/lima](https://www.roscommon.systems/lima) |

The two work well together: keep the add-on installed for quick questions inside NVDA, and use the desktop app when you want the complete AI experience.

### How the add-on works

Sign-in uses Google OAuth and Firebase under the hood, and every AI call goes through the LIMA backend proxy, so no API key or provider secret ever lives in the add-on. Screenshots leave your device only when you trigger a feature, and they travel under a Zero Data Retention policy.

!!! tip "Sign in once, stay signed in"
    Sign in from **NVDA menu → Preferences → Settings → LIMA AI → Sign in with Google**. Your session is refreshed automatically, so you don't have to repeat the sign-in.

### Next steps

- [Install the add-on](https://docs.roscommon.systems/nvda-addon/installation/)
- [Quick Start guide](https://docs.roscommon.systems/nvda-addon/quick-start/)
- [Browse all features](https://docs.roscommon.systems/nvda-addon/features/)
- [Keyboard Shortcuts](https://docs.roscommon.systems/nvda-addon/keyboard-shortcuts/)

### Using these docs with an AI assistant

All of the LIMA AI NVDA Add-on documentation is also available as a single text file: [LIMA AI NVDA Add-on documentation for AI assistants](https://docs.roscommon.systems/nvda-addon/llms-full.txt). Give this link to an AI assistant and it can read every page at once, rather than one page at a time.

## Installation

Source: https://docs.roscommon.systems/nvda-addon/installation/

### System Requirements

These are the requirements for using the LIMA AI NVDA add-on.

| Requirement | Details |
| --- | --- |
| Operating system | Windows, with NVDA 2023.1 or later installed |
| Internet connection | Required for the AI features |
| Google account | Used to sign in — no separate password to create |

### Install from the NVDA Add-on Store

The recommended way to install LIMA AI is from the NVDA Add-on Store.

1. **Open the Add-on Store** — from the NVDA menu, select **Tools, then Add-on Store**.
2. **Find LIMA AI** — go to the **Available add-ons** tab and search for `LIMA AI`.
3. **Install** — with LIMA AI focused in the list, press `Enter`, then choose **Install** from the actions menu.
4. **Restart NVDA** when prompted so the add-on starts running.

!!! note "Keeping it up to date"
    NVDA checks the Add-on Store for updates and notifies you after startup when any are available. Updates for LIMA AI appear in the **Updatable add-ons** tab — press `Enter` on the add-on and choose **Update**.

### Install from an external source

If you have the add-on package (a `.nvda-addon` file) from the Roscommon Systems website or another trusted source:

1. Open the **Add-on Store** (NVDA menu → Tools → Add-on Store).
2. Press the **Install from external source** button and browse to the downloaded `LIMA...nvda-addon` file.
3. Confirm the installation when asked.
4. **Restart NVDA** when prompted.

!!! tip "Next step: sign in"
    After NVDA restarts, the next step is to sign in with your Google account — see the [Quick Start guide](https://docs.roscommon.systems/nvda-addon/quick-start/).

### Verify the installation

- Open **NVDA menu → Preferences → Settings** and confirm a **LIMA AI** category is listed.
- Open **NVDA menu → Preferences → Input Gestures**, expand the **LIMA AI** category, and check that the five default gestures are assigned. See [Keyboard Shortcuts](https://docs.roscommon.systems/nvda-addon/keyboard-shortcuts/).

### Uninstall or disable

1. Open the **Add-on Store** (NVDA menu → Tools → Add-on Store).
2. Go to the **Installed add-ons** tab and focus LIMA AI.
3. Press `Enter`, then choose **Remove** — or choose **Disable** to keep the add-on installed but stop it from loading.
4. Restart NVDA when prompted.

### Next steps

- [Quick Start guide](https://docs.roscommon.systems/nvda-addon/quick-start/) — sign in and describe your first screen
- [Features](https://docs.roscommon.systems/nvda-addon/features/) — what the add-on can do
- [Settings](https://docs.roscommon.systems/nvda-addon/settings/) — language and web narration options

## Quick Start

Source: https://docs.roscommon.systems/nvda-addon/quick-start/

This guide gets you from installation to your first AI screen description in four steps.

### Step 1 — Install the add-on

If you haven't installed LIMA AI yet, follow the [Installation guide](https://docs.roscommon.systems/nvda-addon/installation/). NVDA must be restarted after installing before LIMA AI appears in your settings.
The first time NVDA starts with LIMA AI installed, it speaks a short welcome that names the main shortcuts.
Note that privacy features that blur or black out the screen, such as the Screen Curtain, can prevent the add-on from working properly. Disable these features to use the add-on.

### Step 2 — Sign in with Google

1. Open **NVDA menu → Preferences → Settings**, then select **LIMA AI** from the category list.
2. Choose **Sign in with Google**. Your default browser opens so you can pick your Google account, then returns you to NVDA.
3. The status line in the settings panel confirms that you are signed in.

!!! tip "Sign in once, stay signed in"
    LIMA AI remembers your session and refreshes it automatically, so you only sign in once — not at every launch.

### Step 3 — Describe your screen

Press `NVDA+Alt+D`. LIMA AI captures the active monitor and NVDA speaks a brief, factual description — the main elements and any important visible text. The description is also shown on your braille display, if you use one.

### Step 4 — Try web narration

1. Open a web page in Chrome, Firefox, Edge, or another supported browser.
2. Press `NVDA+Alt+W` to switch web narration on.
3. Wait for the page to change — a live score, a chat message, a news feed updating.
4. Within a few seconds, NVDA announces the change: *"Web page update: ..."*.
5. Press `NVDA+Alt+W` again to switch narration off.

!!! note "Web narration is for browsing"
    Web narration only runs while a browser window is in focus. It stops by itself when you leave the browser, and it never interrupts your reading or repeats the same update twice.

### Your first commands

| Press | What happens |
| --- | --- |
| `NVDA+Alt+D` | Describes the current screen |
| `NVDA+Alt+E` | Describes the control you are on |
| `NVDA+Alt+W` | Turns dynamic web narration on or off |
| `NVDA+Alt+C` | Clicks a control you describe |
| `NVDA+Alt+U` | Says how much of this month's AI credit you have used |

### Next steps

- [Browse all features](https://docs.roscommon.systems/nvda-addon/features/)
- [Customise shortcuts](https://docs.roscommon.systems/nvda-addon/keyboard-shortcuts/)
- [Change language and narration options](https://docs.roscommon.systems/nvda-addon/settings/)
- [Troubleshooting and support](https://docs.roscommon.systems/nvda-addon/support/)

## Features

Source: https://docs.roscommon.systems/nvda-addon/features/

### Describe the Screen

Press `NVDA+Alt+D` and LIMA AI tells you what is on your screen — on demand, whenever you need it.

- **What you hear** — a brief, factual summary of the active monitor: the main elements and any important visible text, in short spoken sentences. No storytelling, no interpretation — just what is there.
- **Braille too** — the description is also shown on your braille display.
- **One description at a time** — if you press the shortcut while an earlier description is still in progress, NVDA tells you and keeps going.
- **Requires sign-in** — the feature works only while you are signed in with your Google account.

### Describe the Focused Element

Press `NVDA+Alt+E` and LIMA AI describes the control you are on: how it looks and what it does.

- **What it looks at:** a picture of the element together with its accessibility information, such as its name and role. This helps most with buttons and icons that have no label, or only a vague one.
- **Braille too:** the description is also shown on your braille display.
- **Works in browse mode:** on a web page, it describes the element at your browse mode cursor, not the whole page.
- **When there is nothing to capture:** if the focused element has no visible location on the screen, NVDA says so. Move to a control and try again.

### Click by Description

Some controls are easiest to reach with a mouse. Press `NVDA+Alt+C`, type what you want to do in plain words, and press `Enter`. For example: *"click the Send button"*, *"open the Downloads folder"*, or *"right-click the file"*.

- **Finds the real control:** LIMA AI lists the controls on the screen from the accessibility tree, and the AI picks the one you mean. The click lands on that control, never on a guessed position.
- **Single, double, or right click:** chosen from your wording.
- **Works on:** buttons, links, menu items, list items, and text fields such as search and address bars.
- **While it searches:** you hear a short tone and *"Finding ..."* with your own words, then a soft tick until it is done. NVDA then says what it clicked, for example *"Clicked Send."*
- **Cancel at any time:** press `Escape` in the prompt, or press `NVDA+Alt+C` again while it is searching.
- **Nothing found, nothing clicked:** if no control matches, NVDA says *"I could not find ..."* and nothing is clicked.

### Dynamic Web Narration

Press `NVDA+Alt+W` and LIMA AI watches the browser page you are on, briefly announcing when it changes.

- **"Web page update: ..."** — the add-on describes what changed on the page.
- **Non-interrupting** — announcements are spoken between what NVDA is reading, so your reading is never cut off.
- **No repeats** — the same update is never spoken twice.
- **Ignores your own actions** — typing, scrolling, and mouse movement are not narrated.
- **Stays in the browser** — narration runs only while a browser window is focused, and stops by itself when you leave the browser or press `NVDA+Alt+W` again.
- **Before each update** — choose between hearing *"Web page update:"* spoken, a short beep, or nothing before the description. See [Settings, then Web Narration](https://docs.roscommon.systems/nvda-addon/settings/#web-narration).

### Sign In with Google

Sign in once and the add-on recognises you.

- One-time sign-in from NVDA's settings panel — no separate password to create or remember.
- The session is remembered and refreshed automatically, so there's no sign-in at every launch.
- Use the same Google account you use with other Roscommon Systems products.

### Check Your Credit Usage

Each plan includes a monthly amount of AI credit. Press `NVDA+Alt+U` to hear how much of it you have used, for example *"Credits used this month: 34.25%"*, followed by when it resets, such as *"resets in 4 days"*.

- **Also in the settings panel:** the same line is shown under **Credit usage** in the LIMA AI settings.
- **When it is all used:** instead of a general error, NVDA says *"You've used all your LIMA credit for this month."* followed by the date it comes back.
- **Other answers:** if your credit is a one-time amount rather than monthly, NVDA says it does not reset. If the usage can't be checked, for example without an internet connection, NVDA says *"Credits used: Not available"* rather than guessing.
- **Nothing sensitive on your computer:** the LIMA backend works out the percentage from your account, so no API key or dollar amount reaches your computer.

### Speak in Your Language

Descriptions are spoken in the reply language you choose: **English** (default), **Tagalog**, or **Vietnamese**. NVDA uses a matching voice where one is available. With Vietnamese, the add-on's own messages, such as *"Describing screen"*, are in Vietnamese too. See [Settings, then Language](https://docs.roscommon.systems/nvda-addon/settings/#language).

### Privacy by Design

- Screenshots leave your device only when you use a feature. A shortcut sends one when you press it. While web narration is on and a browser is in focus, the add-on compares the screen on your computer every few seconds and sends screenshots only when the page has changed.
- Describing the focused element also sends its accessibility information, such as its name, role, and value. In a text field, the value is the text in it.
- Clicking by description also sends the words you type and the names of the controls on the screen.
- Everything is sent under a **Zero Data Retention** policy: the AI providers may not store or train on it.
- No API key or provider secret lives in the add-on — the LIMA backend attaches keys server-side.
- Nothing else you type, nothing on your clipboard, and no audio is ever collected.

### What the add-on deliberately doesn't do

LIMA AI is the on-demand companion to [LIMA Desktop](https://docs.roscommon.systems/lima/). It does not read documents continuously, take voice commands, or carry out multi-step tasks for you. Those capabilities stay exclusive to the desktop app. For quick AI answers and single clicks inside NVDA, the add-on is all you need.

### Next steps

- [Quick Start guide](https://docs.roscommon.systems/nvda-addon/quick-start/) — sign in and describe your first screen
- [Keyboard Shortcuts](https://docs.roscommon.systems/nvda-addon/keyboard-shortcuts/) — change or add gestures
- [Settings](https://docs.roscommon.systems/nvda-addon/settings/) — language and web narration options

## Keyboard Shortcuts

Source: https://docs.roscommon.systems/nvda-addon/keyboard-shortcuts/

LIMA AI provides five default gestures using the `NVDA+Alt` layer, so they never conflict with an NVDA built-in command. All of them are fully customisable in NVDA's Input Gestures dialog.

### Default Shortcuts

| Shortcut | Action |
| --- | --- |
| `NVDA+Alt+D` | **Describe the screen:** captures the active monitor and speaks a brief description |
| `NVDA+Alt+E` | **Describe the focused element:** says how the control you are on looks and what it does |
| `NVDA+Alt+W` | **Toggle dynamic web narration** on or off |
| `NVDA+Alt+C` | **Click by description:** type what you want to click, and LIMA AI finds the control and clicks it |
| `NVDA+Alt+U` | **Check credit usage:** says how much of this month's AI credit you have used and when it resets |

!!! note "Health check command"
    The add-on also provides an **Announces that the LIMA AI add-on is running** command with no default gesture. If you want one, for example to check that LIMA AI is active, assign any free combination under the **LIMA AI** category in the Input Gestures dialog.

### Customising Shortcuts

All of the add-on's commands appear under the **LIMA AI** category in NVDA's Input Gestures dialog.

1. Open **NVDA menu → Preferences → Input Gestures**.
2. Expand the **LIMA AI** category.
3. Focus the command you want to change.
4. Choose **Add**, press your desired key combination, then press `Enter` to assign it.
5. To remove an existing gesture, focus it in the list and choose **Remove**.

!!! warning
    Avoid combinations already used by your operating system or other screen readers. NVDA itself uses `Insert` (or `Caps Lock`) as its modifier key, so the `NVDA+Alt` layer is a safe choice that is unlikely to clash.

### Next steps

- [Settings](https://docs.roscommon.systems/nvda-addon/settings/) — language and web narration options
- [Support](https://docs.roscommon.systems/nvda-addon/support/) — troubleshooting shortcuts that don't work

## Settings

Source: https://docs.roscommon.systems/nvda-addon/settings/

Open LIMA AI settings from **NVDA menu → Preferences → Settings**, then select **LIMA AI** from the category list.

### Google Account

| Setting | Description |
| --- | --- |
| **Status** | Shows which Google account is signed in, or that you aren't signed in yet |
| **Credit usage** | How much of this month's AI credit you have used and when it resets: the same line `NVDA+Alt+U` speaks. Read only. |
| **Sign in with Google** | Opens your default browser to sign in with your Google account, then returns you to NVDA |
| **Sign out** | Shown in place of **Sign in with Google** once you are signed in. Ends the session immediately, and AI features stop working until you sign in again. |

The AI features work only while you are signed in. If you use one while signed out, NVDA says *"Sign in with Google in LIMA AI settings to use this feature."*

### Language

| Setting | Description |
| --- | --- |
| **Language** | The reply language LIMA AI uses for its descriptions. Options: English (default), Tagalog, Vietnamese. |

When Tagalog or Vietnamese is selected, replies are tagged with that language so NVDA speaks them with a matching voice where one is available. With Vietnamese, the add-on's own messages, such as *"Describing screen"* and *"Web page update:"*, are spoken in Vietnamese too. The credit usage line is available in all three languages. The settings panel and the first-run welcome message are in English.

!!! note "Tagalog voices"
    Tagalog is pronounced correctly only when your speech synthesizer has a Filipino voice. NVDA's built-in **eSpeak NG** supports Filipino — select it in **Settings → Speech → Synthesizer**. Windows OneCore voices do not include Filipino and will mispronounce Tagalog.

!!! note "Vietnamese voices"
    Vietnamese is pronounced correctly only when your speech synthesizer has a Vietnamese voice, such as **eSpeak NG**. Also turn on **Automatic language switching (when supported)** in **Settings → Speech**, so NVDA switches to the Vietnamese voice for LIMA AI's replies.

### Web Narration

| Setting | Description |
| --- | --- |
| **Announce before each update** | What happens before a web update is described. Options: **Speak text** (default) — NVDA says *"Web page update:"*; **Play a sound** — a short beep; **Off** — the description itself is spoken with nothing before it. |

!!! info "Advanced settings"
    The interval between page checks (6 seconds by default) and the change-detection threshold are not exposed in this panel; the defaults suit most users. Advanced users can adjust them in NVDA's configuration.

### Next steps

- [Keyboard Shortcuts](https://docs.roscommon.systems/nvda-addon/keyboard-shortcuts/) — change or add gestures
- [Features](https://docs.roscommon.systems/nvda-addon/features/) — what the add-on can do
- [Support](https://docs.roscommon.systems/nvda-addon/support/) — troubleshooting and contact details

## Support

Source: https://docs.roscommon.systems/nvda-addon/support/

### Troubleshooting

#### I can't sign in with Google

1. Check your internet connection — signing in needs a working connection to confirm your account.
2. Make sure you finish choosing your account **in the browser window that opens**, then return to NVDA. If no browser opens, check that you have a default browser set on Windows.
3. Try again from **NVDA menu → Preferences → Settings → LIMA AI → Sign in with Google**.
4. If the problem persists, contact support with the email address you were signing in with.

#### The add-on says "Sign in with Google in LIMA AI settings to use this feature"

Every AI feature requires you to be signed in.

1. Open **NVDA menu → Preferences → Settings → LIMA AI**.
2. Choose **Sign in with Google** and complete the sign-in in the browser.
3. Try the feature again.

#### A description fails or says it can't reach the AI service

- Check your internet connection.
- Press the shortcut again, for example `NVDA+Alt+D`. The AI service may have been temporarily unavailable.
- If other internet features on your computer work but the add-on still fails, contact support with the exact wording NVDA spoke.

#### Web narration doesn't announce anything

Web narration is designed to announce only **meaningful changes** — it stays quiet on a static page, and it never interrupts your reading.

- Confirm that a **browser window is in focus**. Narration pauses automatically whenever you leave the browser.
- Make sure web narration is switched on (`NVDA+Alt+W`).
- Try a page that changes live — a live score, a chat, or a news feed — and wait a few seconds for the next check.
- Keep listening while you read: the announcement is queued between NVDA's normal speech, not instead of it.

#### The description is wrong or incomplete

- Descriptions are brief and factual by design — they summarise the main elements and important visible text.
- Press `NVDA+Alt+D` again for a fresh description.
- Privacy features that blur or black out the screen, such as the Screen Curtain, can prevent the add-on from working properly. Disable them to use the add-on.

#### Describing the focused element says it has no visible location

NVDA says *"The focused element has no visible location to capture. Move to a control and try again."* when the element you are on is not drawn on the screen, so there is nothing to capture.

- Move to a visible control, such as a button, link, or field, with `Tab` or the arrow keys.
- Press `NVDA+Alt+E` again.

#### Click by description can't find the control

- Use the words written on the control, for example *"click Save"* rather than *"keep my work"*.
- Make sure the control is visible in the current window. LIMA AI looks only at what is on the screen.
- Some apps draw controls that are not exposed to screen readers. LIMA AI can't click those, because it only clicks controls found in the accessibility tree.

#### LIMA AI says I've used all my credit

NVDA says *"You've used all your LIMA credit for this month."* followed by the date it resets. The AI features work again from that date. Press `NVDA+Alt+U` at any time to hear how much you have used and when it resets. If you think the limit was reached in error, contact support.

#### Credit usage says "Not available"

NVDA says *"Credits used: Not available"* when the add-on can't check your usage.

- Check that you are signed in and that your internet connection works.
- Press `NVDA+Alt+U` again in a moment. The LIMA service may have been briefly unavailable.

#### Tagalog is pronounced incorrectly

Tagalog is spoken correctly only when your synthesizer has a Filipino voice. NVDA's built-in **eSpeak NG** supports Filipino:

1. Open **NVDA menu → Preferences → Settings → Speech**.
2. Set **Synthesizer** to **eSpeak NG** and choose a Filipino voice.
3. If it sounds too fast, lower the **Rate** and turn off **Rate boost**.

Windows OneCore voices do not include Filipino, so Tagalog is not pronounced correctly on those.

#### Vietnamese is pronounced incorrectly

Vietnamese is spoken correctly only when your synthesizer has a Vietnamese voice and NVDA switches to it:

1. Open **NVDA menu → Preferences → Settings → Speech**.
2. Set **Synthesizer** to **eSpeak NG**, or another synthesizer with a Vietnamese voice.
3. Turn on **Automatic language switching (when supported)**.

#### Shortcuts aren't working

- Check the gesture is still assigned: **NVDA menu → Preferences → Input Gestures → LIMA AI**.
- Another application or add-on may be intercepting the combination — assign a different gesture from the same dialog.
- Confirm the add-on is enabled in the **Installed add-ons** tab of the Add-on Store.

#### The add-on stopped working after an NVDA update

- Confirm your NVDA version is supported — LIMA AI requires NVDA 2023.1 or later (check in **Help → About NVDA**).
- Restart NVDA.
- If the problem persists, reinstall the add-on from the Add-on Store, or update it from the **Updatable add-ons** tab if an update is listed.

---

### Contact Support

If you can't resolve your issue with the steps above, our support team is here to help.

| Channel | Details |
| --- | --- |
| **Email** | hello@roscommonsystems.com |

!!! tip
    When contacting support, include your **NVDA version** (from **Help → About NVDA**), the **LIMA AI add-on version** (shown in the **Installed add-ons** tab of the Add-on Store), and a brief description of what you were doing when the issue occurred. This helps us resolve your issue faster.