🤖 Error Simplifier — AI for Beginners

Transform cryptic compiler errors into friendly, step-by-step explanations — powered by AI.

Built for students and beginners who struggle to understand error messages from C, C++, Python, Java, JavaScript, and dozens of other languages.

✨ What It Does

When your code has an error, VS Code shows a red underline. This extension:

1. Detects the error automatically when your cursor is on the error line
2. Sends the error + surrounding code to an AI (Claude or GPT-4o)
3. Returns a beginner-friendly explanation in plain English
4. Shows the explanation in a hover tooltip AND a dedicated side panel

Example

Original error (Python):

NameError: name 'usernmae' is not defined

What Error Simplifier shows:

1️⃣ What happened
You used a variable called 'usernmae' but Python can't find it anywhere.

2️⃣ Why it happened
This is a typo! You wrote 'usernmae' but you probably meant 'username'.
Think of it like calling someone the wrong name — Python doesn't know who you mean.

3️⃣ How to fix it
• Check line 5 for a spelling mistake in the variable name
• Make sure you defined 'username' before using it
• Python is case-sensitive: 'Username' and 'username' are different!

4️⃣ Fixed code example
username = "Alice"   # ← correct spelling
print(username)      # ← now Python can find it ✓

You're doing great — typos happen to everyone, even professionals! 💪

🚀 Getting Started

Step 1: Install the Extension

From VS Code Marketplace:

1. Open VS Code
2. Press Ctrl+P (Windows/Linux) or Cmd+P (Mac)
3. Type: ext install error-simplifier
4. Press Enter

From VSIX file:

code --install-extension error-simplifier-1.0.0.vsix

Step 2: Get an API Key

You need an API key from one of these providers:

Step 3: Add Your API Key

1. Open VS Code Settings: Ctrl+, (Windows/Linux) or Cmd+, (Mac)
2. Search for "Error Simplifier"
3. Paste your API key into Error Simplifier: Api Key
4. Set Error Simplifier: Provider to anthropic or openai

🎮 How to Use

Automatic Mode (default)

Just write code normally. When your cursor sits on an error line for 1.5 seconds, the explanation appears automatically.

Manual Mode

• Hover over any red underline → see the explanation in the tooltip
• Right-click on an error → select "Explain Error in Simple English"
• Command Palette (Ctrl+Shift+P) → search "Explain Error in Simple English"
• Status Bar → click "💡 Error Simplifier" at the bottom right

Side Panel

• Shows full explanation history
• Click ▼ to expand/collapse entries
• 📋 Copy explanation button to copy text
• Supports 20 recent explanations per session

⚙️ Settings Reference

Default Models

🔧 Commands

🏗️ Project Structure

error-simplifier/
├── package.json              ← Extension manifest, commands, settings
├── tsconfig.json             ← TypeScript compiler config
├── .eslintrc.json            ← Linting rules
├── .vscodeignore             ← Files excluded from packaged extension
├── README.md                 ← This file
└── src/
    ├── extension.ts          ← Entry point; wires all modules together
    ├── llmService.ts         ← AI provider abstraction (Anthropic, OpenAI, Mock)
    ├── diagnosticsListener.ts← Watches VS Code errors, triggers AI calls
    ├── hoverProvider.ts      ← Hover tooltip implementation
    └── webviewPanel.ts       ← Side panel with full explanation history UI

Architecture

VS Code Diagnostics
        │
        ▼
DiagnosticsListener       ← debounce + context extraction
        │
        ▼
LLMService                ← provider-agnostic, cached
        │
   ┌────┴──────────┐
   ▼               ▼
HoverProvider   WebviewPanel
(tooltip)       (side panel)

💻 Running Locally (Development)

Prerequisites

• Node.js 18+
• VS Code 1.85+
• Git

Setup

# 1. Clone the repository
git clone https://github.com/your-username/error-simplifier
cd error-simplifier

# 2. Install dependencies
npm install

# 3. Compile TypeScript
npm run compile

# 4. Open in VS Code
code .

Launch the Extension

1. Open the project in VS Code
2. Press F5 — this opens a new "Extension Development Host" window
3. In the new window, open any file with code errors
4. The extension is now active!

Watch Mode (auto-recompile on save)

npm run watch

Then press F5 to launch. Every time you save a .ts file, it recompiles automatically. Press Ctrl+Shift+F5 to restart the extension host.

Testing the Extension

Without an API key (Mock mode):

1. Open VS Code Settings
2. Set errorSimplifier.provider to mock
3. Open any file and introduce a syntax error (e.g., delete a semicolon in JS)
4. Move cursor to the red line — a mock explanation appears

With a real API key:

1. Set your key in settings
2. Set provider to anthropic or openai
3. Same steps as above — you'll see real AI-generated explanations

📦 Packaging the Extension

Install the VS Code Extension CLI

npm install -g @vscode/vsce

Create the VSIX package

# Compile first
npm run compile

# Package
npm run package
# OR directly:
vsce package

This creates error-simplifier-1.0.0.vsix in the project root.

Install the packaged extension locally

code --install-extension error-simplifier-1.0.0.vsix

🌐 Publishing to VS Code Marketplace

Step 1: Create a Publisher Account

1. Go to marketplace.visualstudio.com/manage
2. Sign in with your Microsoft account
3. Click "Create publisher"
4. Choose a publisher ID (e.g., john-doe)
5. Update package.json:

   "publisher": "john-doe"
   

Step 2: Get a Personal Access Token (PAT)

1. Go to dev.azure.com → User Settings → Personal Access Tokens
2. Click "New Token"
3. Set:
   • Name: vsce-publish
   • Organization: All accessible organizations
   • Scopes: Marketplace → Manage
4. Copy the token (you'll only see it once!)

Step 3: Login and Publish

# Login with your publisher name
vsce login your-publisher-name
# Paste your PAT when prompted

# Publish!
vsce publish

# Or publish with a version bump:
vsce publish minor   # 1.0.0 → 1.1.0
vsce publish patch   # 1.0.0 → 1.0.1
vsce publish major   # 1.0.0 → 2.0.0

Step 4: Verify

Your extension will appear on the marketplace within minutes at: https://marketplace.visualstudio.com/items?itemName=your-publisher-name.error-simplifier

🔒 Security Notes

• Never commit your API key to Git. The extension stores keys in VS Code's settings, not in code.
• For team use, advise each developer to set their own key in User Settings (not Workspace Settings, which may be committed).
• The extension sends only the error message and a small code snippet (~10 lines) to the AI — never your entire codebase.

🛣️ Roadmap / Future Features

• [ ] Support for local LLMs (Ollama, LM Studio) — just add a new case in llmService.ts
• [ ] Language-specific tips (e.g., Python-specific common mistakes)
• [ ] Error frequency tracking ("You've seen this error 5 times")
• [ ] "Apply Fix" button to automatically patch simple errors
• [ ] Chat-style follow-up questions ("Can you explain more about pointers?")
• [ ] Support for warning-level diagnostics (currently errors only)

🤝 Contributing

Pull requests welcome! Please:

1. Fork the repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Follow the existing code style
4. Add comments to new code
5. Test with both mock mode and a real API key
6. Open a PR with a clear description

📄 License

MIT — see LICENSE for details.

💬 Feedback

Found a bug or have a feature request? Open an issue on GitHub.

Rate the extension on the VS Code Marketplace if it helped you! ⭐