AI Context Health Manager

Keep your AI assistant aligned with your project goals, constraints, and terminology.

AI Context Health Manager is a VS Code extension that monitors the "health" of context during conversations with GitHub Copilot and other LLMs. It detects when the AI starts forgetting your project's specific requirements and can automatically restore context when needed.

🆕 What's New in v0.3.0

🧠 Intelligent Multi-Source Scanning

Automatically scans .github/copilot-instructions.md (highest priority!)
Analyzes multiple project files (package.json, requirements.txt, etc.)
Detects frameworks and dependencies
Extracts JSDoc comments and patterns

🔍 Smart Library Detection

Real-time library detection during conversations
Distinguishes between "missing context" vs "new feature"
One-click library context addition
Automatic usage pattern extraction from your code

Read more about intelligent scanning →

🎯 The Problem

When working with AI assistants like GitHub Copilot in long conversations:

❌ The AI "forgets" your project's constraints and requirements
❌ Responses become generic and don't use your project's terminology
❌ The AI contradicts previous recommendations
❌ The context window fills up and important information gets lost

✨ The Solution

AI Context Health Manager continuously monitors three key metrics:

Context Coverage (0-100): Is the AI using your project's concepts and terminology?
Semantic Consistency (0-100): Is the AI contradicting itself?
Token Pressure (0-100%): How full is the context window?

When metrics degrade, the extension can automatically restore context by re-injecting relevant project information.

🚀 Quick Start

Option 1: Interactive Setup Wizard (2 minutes)

1. Install extension
2. Ctrl+Shift+P → "Context Health: Run Setup Wizard"
3. Answer 4 simple questions about your project
4. Done! Start using @context-health in Copilot Chat

Option 2: Enhanced Automatic Project Scan (30 seconds) ⭐ NEW

1. Install extension
2. Open your project folder
3. Ctrl+Shift+P → "Context Health: Auto-Scan Project"
4. Extension intelligently scans:
   • .github/copilot-instructions.md
   • package.json, requirements.txt, etc.
   • README.md, ARCHITECTURE.md
   • Your code structure and patterns
5. Done! Start using @context-health in Copilot Chat

Now detects: Project type, frameworks, dependencies, and automatically generates comprehensive context!

📊 How It Works

1. Define Your Project Context

The extension stores project context in .context/ folder:

.context/
├── goal.md          # Main project objective
├── constraints.md   # Technical/business restrictions
├── decisions.md     # Architecture/design decisions
└── glossary.md      # Project-specific terminology

Two ways to create these files:

Setup Wizard: Interactive guide (manual input)
Auto-Scan: Analyzes your codebase (automatic)

2. Use AI Normally

Just prefix your Copilot questions with @context-health:

@context-health Create a login function with JWT authentication

The extension automatically:

✅ Captures the AI's response
✅ Analyzes it against your project context
✅ Calculates health metrics
✅ Updates the status bar indicator

3. Automatic Context Recovery

When metrics drop below threshold (default: 50):

🟢 Healthy 85% → 🟡 Degrading 65% → 🔴 Critical 45%
                                        ↓
                            ⚠️ Notification appears
                                        ↓
                        "Context health degraded to 45%"
                        [Restore Context] [Remind Later]
                                        ↓
                            User clicks "Restore"
                                        ↓
                    Extension injects relevant context
                                        ↓
                            🟢 Healthy 88% ✅

🎨 Features in Detail

Automatic Monitoring with Chat Participant

No copy/paste needed! Use @context-health in any Copilot conversation:

You: @context-health How should I structure the authentication module?

Copilot: Based on your JWT authentication approach and GDPR constraints...

Extension: ✅ Captured response, analyzed coverage (87%), consistency (92%)
           Status bar updated: 🟢 Healthy 12%

Three Health Metrics

📈 Context Coverage (0-100)

What it measures: How often the AI references your project-specific concepts

Data sources:

Terms from glossary.md (e.g., "JWT", "OAuth2", "RefreshToken")
Constraints from constraints.md (e.g., "GDPR compliance", "200ms max response time")
Decisions from decisions.md (e.g., "PostgreSQL over MongoDB")
Goal from goal.md

Calculation:

coverage = (terms_found_in_response / total_terms_defined) * 100

Interpretation:

80-100: ✅ AI well-aligned with your project
50-79: ⚠️ Some concepts being missed
0-49: 🔴 AI disconnected from your context

🔄 Semantic Consistency (0-100)

What it measures: Whether the AI contradicts itself

Detection heuristics:

"Now we should..." after "We decided..."
Opposite recommendations within 5 messages
Terminology changes without explanation
Negating previous statements

Calculation:

consistency = 100 - (contradictions_detected * 10)

Interpretation:

80-100: ✅ Coherent responses
50-79: ⚠️ Minor contradictions
0-49: 🔴 AI confused or contradictory

💾 Token Pressure (0-100%)

What it measures: How full the context window is

Calculation:

pressure = (estimated_tokens / max_context_window) * 100

Hybrid estimation:
- Method 1: characters / 3.8
- Method 2: words * 1.3
- Result: weighted average (60% chars, 40% words)

Interpretation:

0-50%: ✅ Plenty of space
50-80%: ⚠️ Approaching limit
80-100%: 🔴 Almost full, consider new conversation

Smart Context Recovery

When does it trigger?

Only when needed (not continuously):

Coverage drops below 50 (configurable)
Consistency drops below 50
Token Pressure exceeds 90%

What does it inject?

The extension injects only relevant context, not everything:

Low Metric	What Gets Injected
Coverage < 50	Glossary + Goal (terminology reminder)
Consistency < 50	Decisions + Constraints (rules reminder)
Token Pressure > 90%	Suggestion to start new conversation

Example injection:

📋 Context Reminder:

**Project Goal**: Build a secure authentication system with JWT

**Key Terms**:
- JWT: JSON Web Token for stateless authentication
- RefreshToken: Long-lived token for obtaining new access tokens
- OAuth2: Third-party authentication protocol

**Active Constraints**:
- All tokens must be encrypted
- Maximum session: 24 hours
- GDPR compliance required

How often?

❌ Not continuously (would pollute conversation)
✅ Only when metrics degrade below threshold
✅ User can accept or decline each injection
✅ Configurable behavior (automatic, notification, silent)

Status Bar Indicator

Live visual feedback in your status bar:

🟢 Context: Healthy 15%      → All metrics >80, pressure <70%
🟡 Context: Degrading 55%    → Some metric 50-79
🔴 Context: Critical 85%     → Metric <50 or pressure >90%
⏸️ Context: Disabled         → Monitoring paused

Click the indicator to open quick menu:

⏸️ Disable/Enable Monitoring
🚀 Run Setup Wizard
🔍 Auto-Scan Project
📊 Show Health Panel
🔄 Refresh Metrics

Context Health Panel

Detailed metrics view with explanations:

┌─────────────────────────────────────────┐
│  Context Health Metrics                 │
├─────────────────────────────────────────┤
│  📈 Context Coverage: 87/100           │
│  AI is actively referencing your       │
│  project concepts. Good alignment!     │
│                                         │
│  🔄 Semantic Consistency: 92/100       │
│  Responses are coherent with minimal   │
│  contradictions detected.              │
│                                         │
│  💾 Token Pressure: 23%                │
│  Plenty of context window space        │
│  available (1,874 / 8,192 tokens).     │
│                                         │
│  ⏰ Last Update: 2:34 PM               │
│  [Refresh Metrics]                      │
└─────────────────────────────────────────┘

Setup Wizard

Interactive 4-step guide for defining context:

Step 1: Project Goal

What is the main goal of your project?
┌─────────────────────────────────────┐
│ Build a REST API for e-commerce    │
│ product management with inventory   │
│ tracking                            │
└─────────────────────────────────────┘

Step 2: Constraints

List technical or business constraints (comma-separated):
┌─────────────────────────────────────┐
│ GDPR compliance, Max 200ms response,│
│ PostgreSQL only, TypeScript strict  │
└─────────────────────────────────────┘

Step 3: Key Decisions

List architectural/design decisions (comma-separated):
┌─────────────────────────────────────┐
│ JWT over sessions, REST over GraphQL│
│ Microservices architecture          │
└─────────────────────────────────────┘

Step 4: Glossary

Define project terms (format: term: definition):
┌─────────────────────────────────────┐
│ SKU: Stock Keeping Unit identifier  │
│ Inventory: Available product stock  │
│ Fulfillment: Order processing system│
└─────────────────────────────────────┘

Result: 4 markdown files created in .context/ folder

Auto-Scan Project

Automatically analyzes your codebase:

What it detects:

Primary programming language (by file count)
Frameworks (from package.json, requirements.txt)
Project type (web app, API, extension, etc.)
Class and interface names
Main functions and exports
Architecture patterns

Example output for a TypeScript React project:

goal.md:

# MyProject

**Type:** TypeScript project
**Framework:** React, Express
**Purpose:** Web application

**Status:** Auto-detected project structure.
Please update this goal with specific project objectives.

glossary.md:

# Project Terminology

- **UserService**: User management and authentication service
- **AuthConfig**: Configuration interface for authentication
- **TokenManager**: Handles JWT token generation and validation
- **ApiClient**: HTTP client for backend communication

constraints.md:

# Technical Constraints

- Node.js >=18 required (from package.json engines)
- TypeScript strict mode enabled
- React 18+ for concurrent features

decisions.md:

# Architecture Decisions

- Frontend framework: React (detected)
- Backend framework: Express (detected)
- State management: Context API (inferred from imports)

⚙️ Configuration

Access via File > Preferences > Settings → "Context Health":

{
  // Enable/disable monitoring
  "contextHealth.enabled": true,
  
  // Model information (informational only)
  "contextHealth.llmProvider": "GitHub Copilot",
  "contextHealth.modelName": "gpt-4",
  "contextHealth.maxContextWindow": 8192,
  
  // Automatic context recovery
  "contextHealth.autoRecovery": true,
  "contextHealth.recoveryThreshold": "Critical",  // "Critical" | "Degrading"
  "contextHealth.injectionMethod": "notification"  // "automatic" | "notification" | "silent"
}

Recovery Modes

notification (recommended):

Shows notification when degradation detected
User decides whether to restore context
Full control over injections

automatic:

Injects context automatically without asking
Best for experienced users who trust the system

silent:

Injects context in background
No notifications shown
Seamless experience

📚 All Commands

Command	Description
`Context Health: Show Health Panel`	Open detailed metrics view
`Context Health: Refresh Metrics`	Recalculate metrics manually
`Context Health: Run Setup Wizard`	Interactive 4-step context setup
`Context Health: Auto-Scan Project`	Analyze code and generate context
`Context Health: Toggle Enabled/Disabled`	Pause/resume monitoring
`Context Health: Set Current Goal`	Define project goal manually
`Context Health: Add Constraint`	Add a single constraint
`Context Health: Add Decision`	Record a design decision
`Context Health: View Current Context`	See loaded context snapshot
`Context Health: Force Context Recovery`	Manually trigger context injection
`Context Health: Preview Recovery Context`	See what would be injected
`Context Health: Clear Context`	Remove all context data
`Context Health: Initialize Workspace`	Create `.context/` folder

Access via: Ctrl+Shift+P → Search "Context Health"

🎯 Use Cases

Onboarding New Team Members

Problem: Junior developers get generic AI responses that don't follow project conventions

Solution:

Team shares .context/ folder in Git
New developer opens project
Auto-scan or use existing context
AI responses automatically align with team standards

Long Development Sessions

Problem: After 50+ messages, Copilot forgets initial requirements

Solution:

Token Pressure metric shows when context is filling up
Auto-recovery restores key information before it's lost
Smooth transition between conversation threads

Strict Compliance Projects

Problem: AI might suggest solutions that violate regulations

Solution:

Define constraints: "GDPR compliant", "PCI DSS Level 1", etc.
Coverage metric ensures AI remembers restrictions
Auto-recovery re-injects constraints if forgotten

Large Refactoring

Problem: AI gives contradictory recommendations across files

Solution:

Semantic Consistency detects contradictions
Decisions log tracks architectural choices
Consistent guidance throughout refactoring

🔒 Privacy & Security

✅ All metrics calculated locally - No external API calls
✅ Context files stored in your workspace - Full control
✅ No data sent to external servers - Your code stays private
✅ Open source - Audit the code yourself

🤔 FAQ

Q: Does this modify my prompts to Copilot?
A: No. The extension only observes responses. When auto-recovery triggers, it injects context as a separate message with user permission.

Q: Will this make my conversations cluttered?
A: No. Context injection only happens when metrics degrade below threshold (not continuously). In notification mode, you can always decline.

Q: Does it work with other LLMs besides Copilot?
A: Currently optimized for GitHub Copilot. The architecture supports other LLMs, but they're not yet integrated.

Q: What if I don't want auto-recovery?
A: Set "contextHealth.autoRecovery": false in settings. You'll still get metrics monitoring without automatic injections.

Q: Can I share context files with my team?
A: Yes! Commit .context/ folder to Git. Everyone on the team gets consistent AI guidance.

Q: How accurate is token estimation?
A: ±15% accuracy using hybrid character/word-based calculation. Good enough for practical use.

🛠️ Technical Details

Architecture:

TypeScript extension for VS Code
Chat Participant API integration
Webview for metrics panel
File system watcher for auto-reload
No external dependencies for calculation

Calculation Performance:

Metrics update: <100ms
File reload: <50ms (debounced 500ms)
No impact on Copilot response time

Supported File Formats:

Context files: Markdown (.md)
Analyzed files: .ts, .js, .py, .java, .cs, .cpp, .go, and more

📖 Documentation

Setup Guide - Detailed setup instructions
Metrics Explained - How metrics are calculated
Testing Guide - How to test the extension
Architecture - Technical architecture overview

🤝 Contributing

Contributions are welcome! Areas of interest:

🐛 Bug fixes and improvements
🌐 Support for additional LLMs
📊 New metric algorithms
🌍 Translations
📚 Documentation improvements

📝 Requirements

Visual Studio Code v1.85.0 or higher
GitHub Copilot extension (for @context-health integration)

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built with ❤️ for developers who want their AI assistants to truly understand their projects.

Version: 0.1.0
Publisher: JonathanIzquierdo
Repository: GitHub

AI Context Health Manager

Jonathan Izquierdo

AI Context Health Manager

🆕 What's New in v0.3.0

🧠 Intelligent Multi-Source Scanning

🔍 Smart Library Detection

🎯 The Problem

✨ The Solution

🚀 Quick Start

Option 1: Interactive Setup Wizard (2 minutes)

Option 2: Enhanced Automatic Project Scan (30 seconds) ⭐ NEW

📊 How It Works

1. Define Your Project Context

2. Use AI Normally

3. Automatic Context Recovery

🎨 Features in Detail

Automatic Monitoring with Chat Participant

Three Health Metrics

📈 Context Coverage (0-100)

🔄 Semantic Consistency (0-100)

💾 Token Pressure (0-100%)

Smart Context Recovery

Status Bar Indicator

Context Health Panel

Setup Wizard

Auto-Scan Project

⚙️ Configuration

Recovery Modes

📚 All Commands

🎯 Use Cases

Onboarding New Team Members

Long Development Sessions

Strict Compliance Projects

Large Refactoring

🔒 Privacy & Security

🤔 FAQ

🛠️ Technical Details

📖 Documentation

🤝 Contributing

📝 Requirements

📄 License

🙏 Acknowledgments