AI Workspace

VS Code Extension - Intelligent orchestration layer that optimizes how AI coding assistants interact with large software projects.

What It Does

AI Workspace is a VS Code extension that wraps a powerful MCP (Model Context Protocol) server. It delivers minimal, optimized context to GitHub Copilot and other AI assistants. Instead of letting AI assistants explore your entire codebase blindly, AI Workspace:

✅ Indexes your project once (TypeScript, JavaScript, and more)
✅ Ranks files by relevance for each task
✅ Tracks conversation health to prevent context bloat
✅ Monitors efficiency with cost analysis and savings recommendations
✅ Auto-configures MCP settings (no manual JSON editing!)

🎯 Perfect For

• Large codebases where Copilot gets lost
• Teams sharing consistent AI workflows
• Developers who want efficient, cost-aware AI assistance
• Projects with complex dependency graphs

Key Features

• Smart Context Delivery: Returns only relevant files based on task description
• Dependency-Aware: Understands relationships between files and modules
• Health Monitoring: Tracks conversation health and recommends handoffs
• Efficiency Analysis: Cost tracking, model usage breakdown, savings opportunities
• One-Click Setup: Install from Marketplace, auto-configures everything
• Status Bar Integration: See server status at a glance
• Easy Commands: Restart, view logs, check health, open docs

Architecture

AI Assistant (Copilot/Claude/Cursor)
         ↓
   MCP Protocol
         ↓
  AI Workspace Server
    ├── Repository Indexer
    ├── Dependency Analyzer
    ├── Context Builder
    ├── Health Engine
    └── SQLite Storage

Quick Start

Option 1: Install from Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X or Ctrl+Shift+X)
3. Search for "AI Workspace"
4. Click Install
5. Reload VS Code when prompted
6. Done! ✅ The extension auto-configures everything

Option 2: Manual Installation (Development)

# Clone repository
git clone https://github.com/gpadillaq/ai-workspace.git
cd ai-workspace

# Install dependencies
npm install

# Build extension and MCP server
npm run build

# Package as .vsix
npm run package

# Install in VS Code
code --install-extension ai-workspace-0.1.7.vsix

Verify It Works

1. Open any workspace in VS Code
2. Look for status bar: 🟢 AI Workspace: Ready
3. Open Copilot Chat (Cmd+I or Ctrl+I)
4. Type: @ai-workspace get context for user authentication

First time? The extension shows a welcome message with quick examples!

You should see tools like get_relevant_context, get_health_score, etc.

📚 Documentation

• MCP_SETUP.md - MCP server setup and verification guide
• MCP_EXTENSION_INTEGRATION.md - 🆕 How VS Code extensions expose MCP servers (for developers/AI agents)
• PROBLEMAS_RESUELTOS.md - What was missing and how it was fixed
• INSTALACION.md - Guía de instalación completa en español
• FAQ.md - Preguntas frecuentes (¿Por qué no veo logs? ¿Cómo funciona en otros proyectos?)
• MONITOREO.md - Cómo monitorear consumo de contexto
• QUICKSTART.md - Quick start guide (English)
• ARCHITECTURE.md - Technical architecture details
• CONFIGURATION.md - Advanced configuration options

MCP Tools Exposed (18 tools)

🚀 New in v0.1.7: Navigation Guide (Phase 1.1)

The MCP server now includes an intelligent navigation guide that answers "where is X?" questions instantly, saving 5-10K tokens by preventing random code exploration.

Query Navigation Guide:

{
  "name": "query_navigation_guide",
  "arguments": {
    "query": "where to add types?"
  }
}

Response:

{
  "answer": "src/types/index.ts",
  "howToModify": "Add interface/type at the bottom. Keep alphabetically organized.",
  "conventions": "All types must be in src/types/index.ts (single source of truth)...",
  "examples": [
    { "task": "Add new tool result type", "files": ["src/types/index.ts"] }
  ],
  "confidence": 0.9
}

Supported Questions:

• "where to add types?" → src/types/index.ts
• "where are database operations?" → src/db/index.ts + conventions
• "how to add new tool?" → 4-file workflow with step-by-step guide
• "where are tests?" → src/**/__tests__/ + testing conventions
• Plus: indexer, server, docs, config locations

Benefits:

• ✅ Instant answers without file exploration
• ✅ Includes related files + step-by-step workflow
• ✅ Provides conventions to avoid mistakes
• ✅ Shows examples of similar tasks
• ✅ Saves 5-10K tokens per session by preventing random navigation

See TOKEN_REDUCTION_ROADMAP.md for upcoming features (Project Onboarding, Related Files, Templates).

🚀 New in v0.1.6: Context Optimization

The MCP server now reduces token consumption by 70-90% on subsequent context calls:

Three Context Delivery Modes:

1. Full Mode (default) - Complete files, use for first call

   {
     "name": "get_relevant_context",
     "arguments": {
       "task": "implement JWT auth",
       "mode": "full",
       "sessionId": "my-session"
     }
   }
   

2. Summary Mode - Metadata only (90% reduction)

   {
     "name": "get_relevant_context",
     "arguments": {
       "task": "review auth exports",
       "mode": "summary"
     }
   }
   

3. Delta Mode - Only changed files (70-95% reduction)

   {
     "name": "get_context_delta",
     "arguments": {
       "sessionId": "my-session",
       "task": "continue JWT auth"
     }
   }
   

How It Works:

• Tracks file hashes (SHA-256) to detect changes
• Caches what was sent per session
• Returns only modified/new files on subsequent calls
• Reports token savings with each delta call

Typical Savings:

• Session before: 3 calls × 25K tokens = 75K tokens
• Session after: 25K + 2.5K + 1.5K = 29K tokens (61% savings)

See CONTEXT_OPTIMIZATION.md for detailed guide.

✨ v0.1.5: Per-Call Model Tracking

The MCP server now tracks which AI model is used for each tool call, enabling:

Multi-Model Cost Analysis:

• Automatically detects model mix (e.g., 60% Sonnet, 25% Opus, 15% Haiku)
• Calculates weighted cost based on actual models used
• Adjusts efficiency scores to account for expensive model choices
• Shows model-specific recommendations in efficiency reports

Manual Model Logging: Use log_session_event to track model changes:

{
  "name": "log_session_event",
  "arguments": {
    "eventType": "model_change",
    "model": "claude-3-opus",
    "previousModel": "claude-3-sonnet",
    "description": "Switching to Opus for complex refactoring"
  }
}

Cost Multipliers:

• Claude Opus: 3.0x baseline
• GPT-4: 2.5x baseline
• Claude Sonnet: 1.0x baseline
• GPT-4o-mini: 0.15x baseline
• Claude Haiku: 0.1x baseline

The efficiency report now shows which models you used and recommends cheaper alternatives for simple tasks.

💰 Cost Efficiency Score (v0.1.4)

The get_cost_efficiency tool helps you "gastar menos" (spend less) by:

• Analyzing your session patterns (messages, duration, file exploration)
• Detecting expensive patterns (long conversations, excessive context, feature switches)
• Providing actionable savings recommendations
• Showing efficiency score (0-100) vs your average
• Using honest proxy metrics (character counts) instead of unreliable cost estimates

See COST_EFFICIENCY_IMPLEMENTATION.md for details.

MCP Resources Exposed

MCP Prompts Available

Testing Locally

Test the server before using it in VS Code:

node test-mcp.js

This sends test requests and verifies the server responds correctly.

📚 Documentation

| generate_handoff | Generate handoff document for new conversation |

Development

# Run in watch mode
npm run dev

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Type check
npm run typecheck

Storage

AI Workspace stores its data in .aiworkspace/ directory:

.aiworkspace/
├── index.db              # SQLite database
├── config.json           # User configuration
├── conversation/         # Conversation checkpoints
└── cache/                # Temporary analysis cache

⚠️ Known Issues & Troubleshooting

Wrong Project Context

Problem: The MCP server returns context from the wrong project (e.g., its own codebase instead of your active workspace).

Why: When using mcp.json configuration without the --workspace argument, the server defaults to process.cwd(), which may be the extension directory instead of your project.

Solution:

Option 1: Use the VS Code Extension (Recommended) The extension automatically passes the correct workspace. Install from Marketplace or .vsix.

Option 2: Configure mcp.json with Explicit Workspace Edit ~/Library/Application Support/Code/User/mcp.json:

{
  "mcpServers": {
    "ai-workspace": {
      "command": "node",
      "args": [
        "/path/to/ai-workspace/dist/server.js",
        "--workspace",
        "/path/to/your/project"
      ]
    }
  }
}

Option 3: Environment Variable

export WORKSPACE_ROOT=/path/to/your/project
code /path/to/your/project

Verify the workspace is correct:

1. Open VS Code Output panel: View → Output
2. Select "MCP Servers" or search for [AI-Workspace]
3. Look for: [AI-Workspace] Workspace: /path/to/actual/workspace

See MCP_SETUP.md for detailed configuration guide.

License

MIT