Terminal Error Helper
When a command fails in the VS Code terminal, this extension explains what went wrong, why, and how to fix it — then can run the fix for you and check that it worked.
Use the AI you already have: GitHub Copilot, Google Gemini, OpenAI GPT, xAI Grok, Groq, Anthropic Claude, or a local model with Ollama (nothing leaves your computer).
How it works
- Run a command in the VS Code terminal. If it fails, a popup appears: Explain & Fix.
- Click it. You get an explanation in a side panel with three sections: Error, Cause, Fix.
- Click ▶ Run Fix. You see the exact commands and confirm before anything runs.
- Click Verify to re-run your original command. If it still fails, the AI is shown what didn't work and tries a different fix (up to 3 times).
Quick start
- Install the
.vsix: Extensions view → ... menu → Install from VSIX… and restart VS Code.
- Click Allow when asked for terminal access.
- Pick a provider and model (Command Palette → Terminal Error Helper: Choose AI Provider & Model).
- Try it: in the VS Code terminal run
npm run doesnotexist, then click Explain & Fix.
Which provider should I pick?
Your API key is stored in VS Code's encrypted secret storage — never in settings files or in this extension.
Features
- Works with many AIs. Switch provider or model any time.
- Project-aware answers. The prompt includes your OS, shell,
package.json scripts and dependencies, Node/Python version, and the source lines named in the error — so the answer fits your project, not a generic one.
- One-click Run Fix. Commands are extracted from the answer. Risky ones (
rm -rf, sudo, git reset --hard, curl … | sh, …) are flagged and left unticked.
- Self-correcting. After a fix, Verify re-runs your original command. If it still fails, the AI gets the new error plus the attempts that failed and tries again.
- Error history and cache. Every analysis is saved. Hit the same error again and you're offered the saved fix instantly — no AI call, no cost, nothing sent. Fixes that passed Verify are marked ✓.
- Secret masking. Tokens, API keys, passwords, JWTs, private keys and credentials in URLs are masked before anything is sent.
- Local option. With Ollama, nothing ever leaves your computer.
Privacy — what is sent, and when
Nothing is sent until you click Explain & Fix (or you turn on autoExplain). Then the following goes to the provider you chose:
- the failed command and the last ~8,000 characters of its output
- project details (OS, shell,
package.json scripts and dependency names, tool versions, a few lines of code around file paths in the error) — switch off with includeProjectContext
Before sending, secrets are masked. Masking is pattern-based, so an unusual secret could slip through. To see exactly what will be sent, turn on previewBeforeSend.
The extension has no telemetry and no server of its own. Each provider handles your data under its own privacy policy — free tiers in particular may allow training on your data, so check theirs. Use Ollama if the output may be sensitive.
You can revoke terminal access at any time: Terminal Error Helper: Allow/Revoke Terminal Access.
Commands
| Command |
What it does |
| Choose AI Provider & Model |
Pick the provider, enter its key, pick a model |
| Set API Key |
Add or replace a provider's key |
| Run Suggested Fix |
Re-open the fix commands from the last analysis |
| Show Error History |
Browse past errors and their fixes |
| Clear Error History |
Delete all saved errors |
| Allow/Revoke Terminal Access |
Turn terminal reading on or off |
| Diagnose |
Show version, permission state and whether each terminal is detected |
Settings
| Setting |
Default |
Description |
terminalErrorHelper.provider / model |
– |
Set by Choose AI Provider & Model |
terminalErrorHelper.autoExplain |
false |
Explain every failed command without asking (also skips the send preview) |
terminalErrorHelper.previewBeforeSend |
true |
Show the masked text and ask before sending to a cloud provider |
terminalErrorHelper.includeProjectContext |
true |
Add project details to the prompt for more specific answers |
terminalErrorHelper.useCache |
true |
Offer the saved fix when you hit a known error |
terminalErrorHelper.maxFixAttempts |
3 |
How many times the AI may retry after a failed fix |
terminalErrorHelper.ollamaUrl |
http://localhost:11434 |
Address of your Ollama server |
Troubleshooting
Run Terminal Error Helper: Diagnose first. It shows:
- Terminal access not allowed → click Allow now.
- Shell integration OFF for your terminal → open a new terminal, and check that
terminal.integrated.shellIntegration.enabled is on.
- Nothing happens on a failed command → make sure you are using the VS Code integrated terminal, not an external window, and run the command after the extension has loaded.
- "Couldn't load models" → the API key is wrong or missing. Choose Re-enter key. For Ollama, make sure it is running (
ollama serve).
- Old behaviour after updating → fully quit VS Code (all windows) and reopen. A window reload alone may keep the old version running.
Requirements and limits
- VS Code 1.93+ with terminal shell integration (on by default).
- Works with PowerShell, bash, zsh, fish and Git Bash. cmd.exe is not supported — set PowerShell as your default terminal on Windows.
- Only the VS Code integrated terminal is watched.
- Verify and automatic retries need shell integration. Without it, commands are still sent to the terminal but the result can't be checked.
- A fix command that never finishes (for example a dev server) keeps the "Running fix…" notice waiting.
Build from source
npm install
npm run compile # build to ./out
Press F5 in VS Code to launch an Extension Development Host, or build an installable package:
npm run package # creates terminal-error-helper-<version>.vsix
License
MIT
| |
