Feature/vscode extension

[BurakKTopal]

PR Description

Summary

This PR adds a Visual Studio Code extension for Codebase Time Machine (CTM) that enables developers to understand the "why" behind code directly from their editor. Users can select any lines of code, right-click, and get AI-powered explanations that trace the full decision chain from code to commits, PRs, and issues. Key capabilities:

• Right-click context menu integration for code investigation
• Multi-provider AI support (Anthropic Claude, OpenAI, Google Gemini)
• Follow-up questions and investigation continuation
• Token-efficient architecture using fact extraction instead of raw output storage
• Automatic MCP server detection (pip/pipx packages or local development with uv)

How It Works

Architecture Overview

The extension follows a state-based agent architecture designed for token efficiency:

Extension Entry Point (extension.ts)

• Registers the ctm.whyDoesThisExist command
• Handles code selection with proper line number calculation (accounts for cursor position at line start)
• Detects GitHub repository info and relative file paths
• Checks for uncommitted changes and warns users about potential line mismatch
• Manages MCP client lifecycle with connection reuse

MCP Client (mcpClient.ts)

• Connects to the CTM MCP server via stdio transport using the @modelcontextprotocol/sdk
• Implements intelligent server detection with priority ordering:
  1. User-configured command (manual override)
  2. Local development mode with uv (when serverPath is set)
  3. pip/pipx package installation (ctm-server in PATH)
  4. Python module directly (python -m ctm_mcp_server.stdio_server)
• Handles cross-platform differences (Windows batch wrapper, Unix shell script)
• Passes GitHub token via environment variable for private repos

Investigation Agent (agent.ts)

• Uses a state-based prompt architecture instead of accumulated conversation history
• Each iteration builds a fresh prompt from current facts rather than appending messages
• Implements a two-phase approach: investigation (tool calls) and synthesis (final answer)
• Limits tool calls to a configurable maximum (default 12) with automatic synthesis at 75%
• Supports investigation continuation and follow-up questions with tool access
• Caches tool results to avoid duplicate API calls

FactStore (factStore.ts)

• The core of the token-efficient architecture
• Extracts durable facts from tool outputs (e.g., "PR #123: Title by Author") instead of keeping raw JSON
• Maintains separate evidence store for verbatim details (emails, full SHAs, timestamps) used during synthesis
• Organizes facts by category (commits, PRs, issues, code, authors)
• Tracks open questions to guide investigation ("What PR introduced this?")
• Supports various tool outputs: get_local_line_context, get_pr, get_issue, pickaxe_search, get_commit_diff, etc.

Provider System (providers/)

• Registry-based multi-provider abstraction
• Common interface (ILLMProvider) with createMessage() method
• Implemented providers:
  • anthropic.ts: Claude Haiku 3.5, Sonnet 4.5, Opus 4.5
  • openai.ts: GPT-4.1 Nano, GPT-4.1, o1
  • gemini.ts: Gemini 2.0 Flash-Lite, 2.5 Flash, 3 Pro
• Each provider normalizes tool call format to common schema

UI Panel (contextPanel.ts)

• Webview panel with VS Code native styling
• Displays structured context (blame commit, PR, linked issues)
• Supports follow-up questions with real-time progress indicators
• "Continue Investigation" button when initial analysis hits tool call limit
• /model command to change AI model on the fly
• Markdown rendering for AI responses

Core Tools

The extension uses a curated subset of 10 tools (from the 35 available) to minimize schema token overhead (constants.ts:23-43):

• get_local_line_context - Primary tool: blame + PR + issues + history in one call
• get_pr, get_issue - Full PR/issue details with comments
• search_prs_for_commit - Find PR from commit SHA
• get_github_file_history, get_github_commits_batch - File and commit analysis
• explain_file, get_commit_diff - File overview and code change diffs
• pickaxe_search - Find when code was added/removed (git -S equivalent)
• get_code_owners - Identify code experts

System Prompt

The agent uses a dedicated system prompt (SYSTEM_PROMPT.md) that:

• Guides investigation strategy (5-step process)
• Explains the git blame problem (last touch vs. original introduction)
• Provides tool selection matrix for different questions
• Defines expected response format (What/When, Why, How, Context, Recommendation)
• Includes quality checklist and investigation pacing guidelines

Configuration

The extension exposes these settings in VS Code (via package.json contributes):

Setting	Default	Description
ctm.provider	anthropic	AI provider (anthropic/openai/gemini)
ctm.apiKey	-	API key for selected provider
ctm.model	claude-3-5-haiku-20241022	Model to use
ctm.maxToolCalls	12	Max tool calls per investigation (3-50)
ctm.serverPath	-	Path to local CTM repo (for development)
ctm.githubToken	-	GitHub token for private repos

Server command/args are auto-detected but can be manually overridden with ctm.serverCommand and ctm.serverArgs.

Tests

The extension includes unit tests using Mocha with the following coverage:

FactStore Tests (factStore.test.ts)

• Empty/error result handling
• Fact extraction from get_local_line_context (blame, PR, issues, historical commits)
• Fact extraction from get_pr (full details, comments, discussions)
• Fact extraction from get_issue
• Fact extraction from get_github_file_history and trace_file_history
• Fact extraction from pickaxe_search (including no-results case)
• Fact extraction from get_commit_diff (files changed, patch parsing)
• Facts summary organization by category
• Investigation state generation
• Context sufficiency checks (hasEnoughContext)
• Evidence extraction (author emails, full SHAs, URLs, timestamps)
• Fact deduplication by ID
• Clear functionality

Provider Tests (providers.test.ts)

• Provider creation (anthropic, openai, gemini)
• Error handling for unknown providers
• Available providers listing
• Models per provider
• All models aggregation
• Provider existence checks
• Display name resolution
• Model field validation (id, label, description, contextWindow)
• Model type verification (haiku/sonnet/opus, gpt-4/o1, flash/pro)

GitHub Utilities Tests (github.test.ts)

• Windows path to relative path conversion
• Unix path to relative path conversion
• Nested directory handling
• Same path edge case
• Single file in root directory

Constants Tests (constants.test.ts)

• Default max tool calls validation
• Synthesis threshold calculation (75% of max, floored)
• Core tools array validation
• Tool inclusion verification (primary, PR/issue, file analysis, archaeology)
• Duplicate detection
• Default provider/model values

Run tests with: npm test

Development Setup

Prerequisites:

• Node.js 16+ and npm 8+
• VS Code 1.80.0+
• CTM server installed (pip/pipx) or local repo with uv

cd extensions/vscode
npm install
npm run compile

Debug with F5 in VS Code to launch Extension Development Host. Build for distribution:

npm run package
# Creates codebase-time-machine-0.1.0.vsix

Install from VSIX:

code --install-extension codebase-time-machine-0.1.0.vsix

Files Changed

extensions/vscode/
  package.json              # Extension manifest
  tsconfig.json             # TypeScript config
  README.md                 # User documentation
  src/
    extension.ts            # Entry point
    mcpClient.ts            # MCP server connection
    agent.ts                # Investigation agent
    factStore.ts            # Token-efficient fact storage
    constants.ts            # Shared constants
    types.ts                # TypeScript types
    SYSTEM_PROMPT.md        # Agent system prompt
    ui/
      contextPanel.ts       # Webview panel
    providers/
      index.ts              # Provider registry
      types.ts              # Provider interfaces
      anthropic.ts          # Claude provider
      openai.ts             # GPT provider
      gemini.ts             # Gemini provider
      providers.test.ts     # Provider tests
    utils/
      github.ts             # GitHub utilities
      github.test.ts        # Path conversion tests
    test/
      setup.ts              # Test setup
      vscode-mock.ts        # VS Code API mock
    factStore.test.ts       # FactStore tests
    constants.test.ts       # Constants tests
docs/
  EXTENSION_DEVELOPMENT.md  # Developer documentation

Test Plan

• Install extension from VSIX on fresh VS Code instance
• Configure API key and verify settings are persisted
• Open a file in a GitHub-linked repository
• Select lines and trigger "CTM: Why does this code exist?" from context menu
• Verify panel shows AI explanation with blame, PR, and issue context
• Ask a follow-up question and verify response
• Test /model command to change model mid-session
• Verify "Continue Investigation" button appears when analysis is incomplete
• Test with uncommitted changes and verify warning dialog
• Test on repository without GitHub remote (should fail gracefully)
• Verify extension works with each provider (anthropic, openai, gemini)
• Run npm test and verify all tests pass