Code Context Explainer

AI-powered code explanations using project context (Micro-RAG). Works with or without an OpenAI API key.

✨ Features

Code Context Explainer helps you understand code faster by providing intelligent explanations with full project context.

🎯 Dual Mode Operation

• ✅ Demo Mode: Works immediately without any API key
  • Language detection
  • Structure analysis (imports, functions, classes)
  • Line count and basic metrics
• 🤖 AI Mode: Full-powered explanations using OpenAI
  • Deep code understanding
  • Architecture insights
  • Custom question answering

🔍 Micro-RAG Context

Automatically gathers context from:

• Current file content
• Project README
• Workspace information

🎨 Clean UX

• Explanations appear as hover overlays (no editor spam)
• Truncates long outputs with "Show Full" option
• Non-intrusive, focused on your workflow

📸 Screenshots

Demo Mode (No API Key)

Instant code analysis with structure detection:

📁 Project Overview
Workspace: my-project

📄 Current File Analysis
File: src/utils/helper.ts
Language: typescript
Lines of Code: 156

Structure:
- Imports: 8
- Functions/Methods: 12
- Classes: 3
- Comment Lines: 24

AI Mode (With OpenAI API Key)

Deep explanations powered by GPT-4:

This module implements a data transformation pipeline using the Strategy pattern.
The DataProcessor class coordinates multiple transformation strategies...

Key Components:
1. DataProcessor - Main orchestrator
2. TransformStrategy - Interface for transformation logic
3. ValidationMiddleware - Pre-processing validation

Architecture Notes:
- Follows SOLID principles
- Uses dependency injection for testability
- Implements error handling with fallback strategies

🚀 Getting Started

Installation

1. Install from VS Code Marketplace
2. Search for "Code Context Explainer"
3. Click Install

Or use command line:

code --install-extension miriamkanner.code-context-explainer

Quick Start (Demo Mode)

1. Open any code file
2. Press Ctrl+Shift+E (Windows/Linux) or Cmd+Shift+E (Mac)
3. View explanation hover above your code

No API key needed! Demo mode works immediately.

Enable AI Mode

1. Get an OpenAI API key from platform.openai.com
2. Open VS Code Settings (Ctrl+, or Cmd+,)
3. Search for "Code Context Explainer"
4. Enter your API key in openaiApiKey setting
5. Run explain command again for AI-powered insights

Or use the command:

• Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
• Run: "Code Context: Configure OpenAI API Key"

⌨️ Commands

⚙️ Configuration

Access via: File > Preferences > Settings > Extensions > Code Context Explainer

💡 Usage Examples

General Code Explanation

Open any file and press Ctrl+Shift+E:

• Understand what the code does
• See how it fits into the project
• Get architecture insights

Custom Questions

Use "Explain Code with Custom Query" to ask:

• "What design patterns are used here?"
• "How does this handle errors?"
• "What are the performance implications?"
• "How does this integrate with the rest of the codebase?"

README Context

The extension automatically includes your project's README, so explanations reference:

• Project purpose
• Architecture decisions
• Conventions and patterns

🏗️ Architecture

Clean, modular design for maintainability:

src/
├── context/         # Project context collection (Micro-RAG)
├── llm/            # OpenAI client & demo responder
├── prompts/        # Prompt construction
├── services/       # Orchestration logic
├── ui/             # Hover rendering
└── extension.ts    # Entry point

See ARCHITECTURE.md for detailed technical design.

🔒 Privacy & Security

• No telemetry: Zero data collection
• Secure storage: API keys stored in VS Code settings (encrypted)
• Local processing: Demo mode runs entirely locally
• Transparent: Fully open-source code
• Your control: API calls only when you trigger commands

📋 Requirements

• VS Code: Version 1.54.0 or higher
• Node.js: 20.x or higher (for development)
• OpenAI API Key: Optional (for AI mode)

🐛 Known Issues

• Hover position requires cursor placement (no auto-hover on selection)
• Context limited to current file + README (multi-file support planned)
• Long explanations truncate in hover (use "Show Full" command)

Report issues on GitHub.

🗺️ Roadmap

Future enhancements:

• [ ] Multi-file context analysis
• [ ] Support for more LLM providers (Anthropic Claude, Google Gemini)
• [ ] Local LLM support (Ollama)
• [ ] Export explanations to markdown files
• [ ] Caching for repeated queries
• [ ] Customizable context retrieval strategies

📝 Release Notes

1.0.0 (Initial Release)

• ✅ Dual mode operation (Demo + AI)
• ✅ Hover-based explanation rendering
• ✅ Micro-RAG context collection
• ✅ Support for GPT-4o and GPT-4o-mini
• ✅ Node 20 compatibility (native fetch)
• ✅ Clean modular architecture
• ✅ Zero dependencies at runtime

See CHANGELOG.md for detailed version history.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See ARCHITECTURE.md for codebase overview.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• VS Code Extension API
• OpenAI API
• TypeScript

📧 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ⭐ Rate: VS Code Marketplace

Made with ❤️ for developers who want to understand code faster

1.0.0

Initial release of ...

1.0.1

Fixed issue #.

1.1.0

Added features X, Y, and Z.

Following extension guidelines

Ensure that you've read through the extensions guidelines and follow the best practices for creating your extension.

• Extension Guidelines

Working with Markdown

You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts:

• Split the editor (Cmd+\ on macOS or Ctrl+\ on Windows and Linux).
• Toggle preview (Shift+Cmd+V on macOS or Shift+Ctrl+V on Windows and Linux).
• Press Ctrl+Space (Windows, Linux, macOS) to see a list of Markdown snippets.

For more information

• Visual Studio Code's Markdown Support
• Markdown Syntax Reference

Enjoy!