Troubleshooting · Docs

Command not found

Open a new terminal: the one you installed from may not see the new command yet.
Check Node.js: node --version must say 20 or newer.
Check that npm's global folder is on your PATH. npm prefix -g prints it; the commands live in that folder on Windows and in its bin folder on macOS and Linux.

The key opens another editor, or does nothing

Use a terminal opened after setup, and start a new Claude Code or Codex session in it. Terminals inside VS Code, Cursor or Windsurf start from the editor's own environment: quit the editor completely and start it again.

Check the setting. It should end in .v8-prompt/edit.cmd on Windows or .v8-prompt/edit.sh elsewhere:

echo $VISUAL          # macOS, Linux, Git Bash
$env:VISUAL           # PowerShell
echo %VISUAL%         # Command Prompt

Windows: a VISUAL set by a PowerShell profile script or a system-wide variable wins over the user setting setup writes. Setup says so when it sees one. Remove that setting (from your profile, or System Properties, Environment Variables), then open a new terminal.
macOS and Linux: if setup could not write a shell startup file, it printed the line to add. Add it to the file your shell reads (~/.zshrc, ~/.bashrc), then open a new terminal.
Run v8-prompt setup again: it is safe to repeat.

Ctrl+Shift+. does nothing

Use Ctrl + G, which works in every terminal. The second key is only bound where setup could edit the terminal's settings: Windows Terminal and the VS Code, Cursor and Windsurf terminals. Setup leaves Windows Terminal alone when that key is already bound to something else, or when its settings file contains comments; it tells you which.

Old behaviour after an update

The shortcut runs the copy of the CLI that setup made in ~/.v8-prompt. After npm install -g v8-advanced-prompt, run v8-prompt setup again so the shortcut uses the new version.

Windows paths and PowerShell

A user name with letters such as Ş, ü or é is supported: the launcher refers to your profile folder through its variable, so the path survives. If Node.js itself is installed in a folder whose name has such letters outside your profile, the launcher runs the node on your PATH instead, so make sure one is there.
"Running scripts is disabled on this system" in PowerShell comes from PowerShell's execution policy, which can block the small script npm creates for every global command. Run the command from Command Prompt, call v8-prompt.cmd instead of v8-prompt, or, if your organisation allows it, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
Programs by full path. On Windows, v8 starts git and your editor only from absolute folders on your PATH, never from the repository you are in, so a repository cannot slip in a program of its own. If git is not on your PATH, v8 still works, with less context about the repository.
"v8 can't read its device key" means another program (an antivirus or a sync client) holds ~/.v8-prompt/device.json open. Nothing was changed; close it and try again. A damaged key file is kept beside as device.json.corrupt-<time> and the terminal gets a new key: if it was linked to Pro, run v8-prompt login again.

What a message means

Message	What to do
Can't reach v8. Check your connection.	This computer cannot reach `https://v8labs.app`. Check your connection; on a company network see Corporate networks.
v8 took too long to answer.	Try again. A prompt that times out is not counted.
v8 is busy. Your prompt has not been used; please retry in a few seconds.	Wait a few seconds and press the key again.
Today's 3 free prompts are used. / This week's 10 free prompts are used.	Wait for the reset the message names (00:00 UTC daily, Monday 00:00 UTC weekly), or go Pro.
Free prompts aren't available on this terminal.	This terminal was registered on a busy shared network. Link it to Pro or a Team seat with `v8-prompt login`.
Free use is full for today. Pro keeps working.	The service's free capacity for the day is used up. Try again tomorrow, or go Pro.
Too many requests. Please slow down. / Service capacity reached.	Short-term limits: wait a minute, and stop any script that retries in a loop.
Something went wrong.	Try again. If it repeats on a company network, a filter may be answering instead of v8labs.app (see what a block looks like). Otherwise email support.

In every one of these cases the shortcut leaves your text exactly as you typed it.

Networks, proxies, filters

The CLI talks only to https://v8labs.app on port 443. On a company network, a DNS filter, a firewall or a proxy can block it. Corporate networks explains what to check and what to send to your IT team.

Uninstall

v8-prompt uninstall
npm uninstall -g v8-advanced-prompt

v8-prompt uninstall restores your VISUAL setting to what it was before setup (or removes it if there was none), removes the key bindings setup added, and keeps the backup copies it made. Open a new terminal afterwards. Then, if you want nothing left:

delete the folder ~/.v8-prompt (the terminal's key, undo files, remembered answers, settings and a local history cache);
remove the Claude Code plugin, if you added it: claude plugin uninstall v8@v8labs and claude plugin marketplace remove v8labs;
delete the .v8-prompt-backup- copies next to your shell startup files and terminal settings once you no longer need them.

Your account is separate. Uninstalling does not delete it. To delete it, use Delete account on the Account page, after cancelling any subscription under Billing. While a subscription is still running, including the rest of a period you already cancelled, the page asks you to cancel first; email support@v8labs.app with the subject Privacy request if you need it deleted sooner.

Something is off.Here is the fix.