AI Workspace

VS Code Extension + standalone MCP server - Intelligent orchestration layer that optimizes how AI coding assistants interact with large software projects. Works with GitHub Copilot Chat (via the VS Code extension), the Claude Code CLI, or the GitHub Copilot CLI (via plain MCP registration) - any MCP-compatible client, really.

What It Does

AI Workspace wraps a lightweight MCP (Model Context Protocol) server around your codebase. It delivers minimal, ranked context to GitHub Copilot, Claude Code, and other AI assistants instead of letting them explore your entire codebase blind. AI Workspace:

✅ Indexes your project once (TypeScript, JavaScript, Python, CSS, SQL, and more), then keeps itself fresh incrementally as files change ✅ Ranks files by relevance for each task, combining full-text search (FTS5, including exported symbol names), import centrality, and git-diff awareness (uncommitted/branch-changed files are boosted) ✅ Builds a symbol-level call graph (TS/JS) - not just "file A imports file B," but "function A calls function B" / "class A extends class B" ✅ Finds symbols and code by name instantly, without grepping the repo ✅ Reduces repeat-call token cost with delta/summary context modes (70-95% smaller on the 2nd+ call) ✅ Measures its own efficiency - reports what % of your indexed repo a given call actually sent, and whether its suggestions get used again ✅ Auto-configures MCP settings in VS Code (no manual JSON editing)

🎯 Perfect For

• Large codebases where Copilot (or Claude Code) gets lost
• Teams sharing consistent AI workflows
• Developers who want token/cost-efficient AI assistance
• Projects with complex dependency graphs

Key Features

• Smart Context Delivery: Returns only relevant files based on task description, ranked by text relevance (including symbol names), dependency centrality, and git-diff activity
• Two-Level Dependency Graph: File-level imports and symbol-level calls/extends/implements (TS/JS)
• Symbol & Code Search: Look up a function/class by exact name, or do an open-ended keyword search across the index
• Context Optimization: Delta/summary modes cut repeat-call token usage by 70-95%
• Honest Efficiency Metrics: % of repo not sent and ranking hit-rate, not just internal "tokens saved vs. our own full mode" bookkeeping
• One-Click Setup: Install from Marketplace, auto-configures everything

How It Works

1. Index once: scan the workspace, parse each file, infer domain/responsibility/tags, build both the file-level import graph and (TS/JS) the symbol-level call graph, store everything in one SQLite file (.aiworkspace/index.db).
2. Stay fresh: a file watcher re-parses changed files and updates the graph incrementally - no need to manually reindex as you work.
3. Rank on request: get_relevant_context scores every indexed file against your task description (FTS5 text relevance + import centrality + git-diff signal) and returns only what clears the bar, within a token budget.
4. Optimize repeat calls: subsequent calls in the same session use delta mode - only new/changed files get re-sent.

That's the short version. For the full technical breakdown (ranking algorithm weights, exactly how the symbol graph is resolved, what's tracked in SQLite and what isn't, the two efficiency metrics), see ARCHITECTURE.md.

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)

# From the project root
# 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-*.vsix

Option 3: Claude Code CLI

AI Workspace isn't tied to VS Code - it's published on npm, so Claude Code can use it with no local clone or build:

claude mcp add ai-workspace -- npx -y @drakonode/ai-workspace --workspace "$(pwd)"

See CLAUDE_CODE_SETUP.md for project-scoped .mcp.json setup and how session tracking behaves outside VS Code/Copilot.

Option 4: GitHub Copilot CLI

The same package also works with GitHub Copilot CLI (npm install -g @github/copilot), GitHub's terminal coding agent - not to be confused with Copilot Chat in VS Code:

copilot mcp add ai-workspace -- npx -y @drakonode/ai-workspace

See COPILOT_CLI_SETUP.md for the project-scoped .mcp.json alternative and why --workspace shouldn't be hardcoded in the command above.

Verify It Works

VS Code / Copilot Chat

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, find_symbol, search_code, etc.

Claude Code CLI

1. Run claude mcp list and confirm ai-workspace shows as connected
2. Ask Claude Code to "use get_relevant_context to look at user authentication"

GitHub Copilot CLI

1. Run copilot mcp list and confirm ai-workspace is listed
2. Ask Copilot to "use get_relevant_context to look at user authentication" (approve the tool call when prompted, or run non-interactively with --allow-all-tools)

📚 Documentation

• ARCHITECTURE.md - Full technical deep dive: indexing pipeline, ranking algorithm, the two dependency graphs, context-efficiency metrics, session tracking
• CONTEXT_STORAGE.md - Exactly what's stored in SQLite, what's actually read vs. write-only/dead, and what's never populated
• CONTEXT_RANKING_IMPROVEMENTS.md - Ranking quality analysis, what's shipped vs. deferred (embeddings, per-symbol summaries)
• CLAUDE_CODE_SETUP.md - Using AI Workspace with the Claude Code CLI instead of VS Code/Copilot
• COPILOT_CLI_SETUP.md - Using AI Workspace with GitHub Copilot CLI instead of VS Code/Copilot Chat
• MCP_SETUP.md - MCP server setup and verification guide, including workspace-resolution debugging
• MCP_EXTENSION_INTEGRATION.md - How VS Code extensions expose MCP servers (for developers/AI agents)
• INSTALACION.md - Guía de instalación completa en español
• FAQ.md - Preguntas frecuentes
• QUICKSTART.md - Quick start guide (English)
• CONFIGURATION.md - Advanced configuration options

MCP Tools Exposed (13 tools)

| Tool | Purpose | |------|---------| | get_relevant_context | Get ranked list of relevant files for a task. Ranking combines FTS5 text relevance (path/domain/responsibility/tags + exported symbol names), import centrality, and a git-diff signal (uncommitted/branch-changed files boosted). Response includes repoTokens/percentOfRepoSent - how much of the indexed repo this call actually sent | | get_architecture_summary | Get high-level architecture overview (domains, key components) | | get_dependency_graph | Get file-level dependencies plus symbol-level calls/extends/implements edges (TS/JS) for a specific file | | get_file_summary | Get responsibility, API, and related files for a specific file | | reindex_repository | Force a full re-index of the repository | | get_context_delta | Get only files changed since the last delivery in this session (70-95% token savings) | | get_context_optimization_report | View token-savings stats, current indexed repo size, and ranking hit-rate (how often suggested files got referenced again) | | query_navigation_guide | Ask "where is X?" / "where do I add Y?" questions, answered from the detected project structure | | get_navigation_guide | Get the complete detected navigation map | | get_project_onboarding | Comprehensive project info (structure, key files by centrality, tech stack, conventions, npm scripts) derived entirely from the indexed project - not hardcoded | | get_related_files | Get files related to a base file by relationship type (dependencies/usedBy/tests/similar/transitive) | | find_symbol | Find a function, class, hook, or other exported symbol by exact/substring name across the whole index - returns file + line instead of grepping | | search_code | General keyword search across the index (path/domain/responsibility/tags/symbols) for open-ended queries, e.g. "anything related to rate limiting?" |

Ranking & Search: FTS5 + Git-Diff Awareness, find_symbol, search_code

get_relevant_context ranks files using the FTS5 full-text index (BM25) - covering exported symbol names, not just path/domain/responsibility/tags - so a task description mentioning a specific function or class name matches correctly even if that name isn't in the file's path. Files with uncommitted changes or changes on the current branch get a relevance boost, since that's usually a strong signal for "what this task is actually about." See ARCHITECTURE.md for the exact scoring weights.

Two tools round this out:

• find_symbol - exact-name lookup for a function/class/hook/etc., when you already know what you're looking for:

  { "name": "find_symbol", "arguments": { "query": "validateToken" } }

• search_code - open-ended keyword search across the index, when you don't have a task description or an exact symbol name:

  { "name": "search_code", "arguments": { "query": "rate limit" } }

Navigation Guide

Answers "where is X?" / "where do I add Y?" instantly from the detected project structure, without exploring code:

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

{
  "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
}

Context Optimization

Three delivery modes for get_relevant_context/get_context_delta:

1. Full (default on a session's first call) - complete ranked file list
2. Summary (mode: "summary") - metadata only, ~10x smaller
3. Delta (get_context_delta, or mode: "auto" on repeat calls) - only new/modified files since the last delivery in this session, tracked via SHA-256 file hashes

Every response also reports repoTokens/percentOfRepoSent - the estimated size of your whole indexed repo and how much of it this specific call actually sent - so "did this help" is a real number, not a guess. get_context_optimization_report additionally reports ranking hit-rate: of the files ever suggested, what fraction got referenced again by a later tool call in the same session.

MCP Resources Exposed

| Resource | Purpose | |----------|---------| | aiworkspace://tools | Complete documentation of all available tools with examples | | aiworkspace://status | Current indexing status and repository statistics |

MCP Prompts Available

| Prompt | Purpose | |--------|---------| | analyze_project | Get comprehensive project analysis including architecture | | start_feature | Get relevant context to start working on a new feature |

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.

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 everything in a single SQLite file per project:

.aiworkspace/
└── index.db   # the entire index + session/usage tracking

See CONTEXT_STORAGE.md for exactly what's in there table by table - including what's actively used vs. write-only/legacy.

Troubleshooting

If the server reports the wrong workspace (e.g. describes its own repo instead of your project), see MCP_SETUP.md for how workspace resolution works (--workspace arg → WORKSPACE_ROOT env → cwd fallback) and how to verify which one is active from the server's stderr logs.

License

MIT