Copilot instructions

1# GitHub Copilot Chat Extension - Copilot Instructions
2 
3## Project Overview
4 
5This is the **GitHub Copilot Chat** extension for Visual Studio Code - a VS Code extension that provides conversational AI assistance, a coding agent with many tools, inline editing capabilities, and advanced AI-powered features for VS Code.
6 
7### Key Features
8- **Chat Interface**: Conversational AI assistance with chat participants, variables, and slash commands
9- **Inline Chat**: AI-powered editing directly in the editor with `Ctrl+I`
10- **Agent Mode**: Multi-step autonomous coding tasks
11- **Edit Mode**: Natural language to code
12- **Inline Suggestions**: Next edit suggestions and inline completions
13- **Language Model Integration**: Support for multiple AI models (GPT-4, Claude, Gemini, etc.)
14- **Context-Aware**: Workspace understanding, semantic search, and code analysis
15 
16### Tech Stack
17- **TypeScript**: Primary language (follows VS Code coding standards)
18- **TSX**: Prompts are built using the @vscode/prompt-tsx library
19- **Node.js**: Runtime for extension host and language server features
20- **WebAssembly**: For performance-critical parsing and tokenization
21- **VS Code Extension API**: Extensive use of proposed APIs for chat, language models, and editing
22- **ESBuild**: Bundling and compilation
23- **Vitest**: Unit testing framework
24- **Python**: For notebooks integration and ML evaluation scripts
25 
26## Validating changes
27 
28Choose validation based on the scope and risk of the change. Prefer existing diagnostics and the smallest targeted tests that cover the changed behavior. Do not start `start-watch-tasks`, run a full build, or make type checking a prerequisite for targeted tests solely as a completion ritual.
29 
30If `start-watch-tasks` is already running, use its diagnostics. Start it or run another targeted type check or build when existing diagnostics are unavailable, the change is broad or cross-cutting, it affects build or type configuration, or another validation step reports a compilation problem. `start-watch-tasks` runs the extension, extension-web, simulation-workbench, and esbuild watchers.
31 
32## Project Architecture
33 
34### Top-Level Directory Structure
35 
36#### Core Source Code (`src/`)
37- **`src/extension/`**: Main extension implementation, organized by feature
38- **`src/platform/`**: Shared platform services and utilities
39- **`src/util/`**: Common utilities, VS Code API abstractions, and service infrastructure
40 
41#### Build & Configuration
42- **`.esbuild.mts`**: Build configuration for bundling extension, web worker, and simulation workbench
43- **`tsconfig.json`**: TypeScript configuration extending base config with React JSX settings
44- **`vite.config.ts`**: Test configuration for Vitest unit tests
45- **`package.json`**: Extension manifest with VS Code contributions, dependencies, and scripts
46 
47#### Testing & Simulation
48- **`test/`**: Comprehensive test suite including unit, integration, and simulation tests
49- **`script/simulate.sh`**: Test runner for scenario-based testing
50- **`notebooks/`**: Jupyter notebooks for performance analysis and ML experiments
51 
52#### Assets & Documentation
53- **`assets/`**: Icons, fonts, and visual resources
54- **`CONTRIBUTING.md`**: Architecture documentation and development guide
55 
56### Key Source Directories
57 
58#### `src/extension/` - Feature Implementation
59 
60**Core Chat & Conversation Features:**
61- **`conversation/`**: Chat participants, agents, and conversation flow orchestration
62- **`inlineChat/`**: Inline editing features (`Ctrl+I`) and hints system
63- **`inlineEdits/`**: Advanced inline editing capabilities with streaming edits
64 
65**Context & Intelligence:**
66- **`context/`**: Context resolution for code understanding and workspace analysis
67- **`contextKeys/`**: VS Code context key management for UI state
68- **`intents/`**: Chat participant/slash command implementations
69- **`prompts/`**: Prompt engineering and template system
70- **`prompt/`**: Common prompt utilities
71- **`typescriptContext/`**: TypeScript-specific context and analysis
72 
73**Search & Discovery:**
74- **`search/`**: General search functionality within the extension
75- **`workspaceChunkSearch/`**: Chunked workspace search for large codebases
76- **`workspaceSemanticSearch/`**: Semantic search across workspace content
77- **`workspaceRecorder/`**: Recording and tracking workspace interactions
78 
79**Authentication & Configuration:**
80- **`authentication/`**: GitHub authentication and token management
81- **`configuration/`**: Settings and configuration management
82- **`byok/`**: Bring Your Own Key (BYOK) functionality for custom API keys
83 
84**AI Integration & Endpoints:**
85- **`endpoint/`**: AI service endpoints and model selection
86- **`tools/`**: Language model tools and integrations
87- **`api/`**: Core API abstractions and interfaces
88- **`mcp/`**: Model Context Protocol integration
89 
90**Development & Testing:**
91- **`testing/`**: Test generation and execution features
92- **`test/`**: Extension-specific test utilities and helpers
93 
94**User Interface & Experience:**
95- **`commands/`**: Service for working with VS Code commands
96- **`codeBlocks/`**: Streaming code block processing
97- **`linkify/`**: URL and reference linkification
98- **`getting-started/`**: Onboarding and setup experience
99- **`onboardDebug/`**: Debug onboarding flows
100- **`survey/`**: User feedback and survey collection
101 
102**Specialized Features:**
103- **`notebook/`**: Notebook integration and support
104- **`review/`**: Code review and PR integration features
105- **`renameSuggestions/`**: AI-powered rename suggestions
106- **`ignore/`**: File and pattern ignore functionality
107- **`xtab/`**: Cross-tab communication and state management
108 
109**Infrastructure & Utilities:**
110- **`extension/`**: Core extension initialization and lifecycle
111- **`log/`**: Logging infrastructure and utilities
112- **`telemetry/`**: Analytics and usage tracking
113 
114**VS Code API Type Definitions:**
115- Multiple `vscode.proposed.*.d.ts` files for proposed VS Code APIs including chat, language models, embeddings, and various editor integrations
116 
117#### `src/platform/` - Platform Services
118- **`chat/`**: Core chat services and conversation options
119- **`openai/`**: OpenAI API protocol integration and request handling
120- **`embedding/`**: Vector embeddings for semantic search
121- **`parser/`**: Code parsing and AST analysis
122- **`search/`**: Workspace search and indexing
123- **`telemetry/`**: Analytics and usage tracking
124- **`workspace/`**: Workspace understanding and file management
125- **`notebook/`**: Notebook integration
126- **`git/`**: Git integration and repository analysis
127 
128#### `src/util/` - Infrastructure
129- **`common/`**: Shared utilities, service infrastructure, and abstractions
130- **`vs/`**: Utilities borrowed from the microsoft/vscode repo (readonly)
131 
132### Extension Activation Flow
133 
1341. **Base Activation** (`src/extension/extension/vscode/extension.ts`):
135   - Checks VS Code version compatibility
136   - Creates service instantiation infrastructure
137   - Initializes contribution system
138 
1392. **Service Registration**:
140   - Platform services (search, parsing, telemetry, etc.)
141   - Extension-specific services (chat, authentication, etc.)
142   - VS Code integrations (commands, providers, etc.)
143 
1443. **Contribution Loading**:
145   - Chat participants
146   - Language model providers
147   - Command registrations
148   - UI contributions (views, menus, etc.)
149 
150### Chat System Architecture
151 
152#### Chat Participants
153- **Default Agent**: Main conversational AI assistant
154- **Setup Agent**: Handles initial Copilot setup and onboarding
155- **Workspace Agent**: Specialized for workspace-wide operations
156- **Agent Mode**: Autonomous multi-step task execution
157 
158#### Request Processing
1591. **Input Parsing**: Parse user input for participants, variables, slash commands
1602. **Context Resolution**: Gather relevant code context, diagnostics, workspace info
1613. **Prompt Construction**: Build prompts with context and intent detection
1624. **Model Interaction**: Send requests to appropriate language models
1635. **Response Processing**: Parse and interpret AI responses
1646. **Action Execution**: Apply code edits, show results, handle follow-ups
165 
166#### Language Model Integration
167- Support for multiple providers (OpenAI, Anthropic, etc.)
168- Model selection and switching capabilities
169- Quota management and fallback handling
170- Custom instruction integration
171 
172### Inline Chat System
173- **Hint System**: Smart detection of natural language input for inline suggestions
174- **Intent Detection**: Automatic detection of user intent (explain, fix, refactor, etc.)
175- **Context Collection**: Gather relevant code context around cursor/selection
176- **Streaming Edits**: Real-time application of AI-suggested changes
177- **Version 2**: New implementation with improved UX and hide-on-request functionality
178 
179## Coding Standards
180 
181### TypeScript/JavaScript Guidelines
182- **Indentation**: Use **tabs**, not spaces
183- **Naming Conventions**:
184  - `PascalCase` for types and enum values
185  - `camelCase` for functions, methods, properties, and local variables
186  - Use descriptive, whole words in names
187- **Strings**:
188  - "double quotes" for user-visible strings that need localization
189  - 'single quotes' for internal strings
190- **Functions**: Use arrow functions `=>` over anonymous function expressions
191- **Conditionals**: Always use curly braces, opening brace on same line
192- **Comments**: Use JSDoc style for functions, interfaces, enums, and classes
193 
194### React/JSX Conventions
195- Custom JSX factory: `vscpp` (instead of React.createElement)
196- Fragment factory: `vscppf`
197- Components follow VS Code theming and styling patterns
198 
199### Architecture Patterns
200- **Service-oriented**: Heavy use of dependency injection via `IInstantiationService`
201- **Contribution-based**: Modular system where features register themselves
202- **Event-driven**: Extensive use of VS Code's event system and disposables
203- **Layered**: Clear separation between platform services and extension features
204 
205### Testing Standards
206- **Unit Tests**: Vitest for isolated component testing
207- **Integration Tests**: VS Code extension host tests for API integration
208- **Simulation Tests**: End-to-end scenario testing with `.stest.ts` files
209- **Fixtures**: Comprehensive test fixtures for various scenarios
210 
211### File Organization
212- **Logical Grouping**: Features grouped by functionality, not technical layer
213- **Platform Separation**: Different implementations for web vs. Node.js environments
214- **Test Proximity**: Tests close to implementation (`/test/` subdirectories)
215- **Clear Interfaces**: Strong interface definitions for service boundaries
216 
217## Key Development Guidelines
218 
219### Arrow Functions and Parameters
220- Use arrow functions `=>` over anonymous function expressions
221- Only surround arrow function parameters when necessary:
222 
223```javascript
224x => x + x                    // ✓ Correct
225(x, y) => x + y              // ✓ Correct
226<T>(x: T, y: T) => x === y   // ✓ Correct
227(x) => x + x                 // ✗ Wrong
228```
229 
230### Code Structure
231- Always surround loop and conditional bodies with curly braces
232- Open curly braces always go on the same line as whatever necessitates them
233   - An open curly brace MUST be followed by a newline, with the body indented on the next line
234- Parenthesized constructs should have no surrounding whitespace
235- Single space follows commas, colons, and semicolons
236 
237```javascript
238for (let i = 0, n = str.length; i < 10; i++) {
239    if (x < 10) {
240        foo();
241    }
242}
243 
244function f(x: number, y: string): void { }
245```
246 
247### Type Management
248- Do not export `types` or `functions` unless you need to share it across multiple components
249- Do not introduce new `types` or `values` to the global namespace
250- Use proper types. Do not use `any` unless absolutely necessary.
251- Use `readonly` whenever possible.
252- Avoid casts in TypeScript unless absolutely necessary. If you get type errors after your changes, look up the types of the variables involved and set up a proper system of types and interfaces instead of adding type casts.
253- Do not use `any` or `unknown` as the type for variables, parameters, or return values unless absolutely necessary. If they need type annotations, they should have proper types or interfaces defined.
254 
255## Key APIs and Integrations
256 
257### VS Code Proposed APIs (Enabled)
258The extension uses numerous proposed VS Code APIs for advanced functionality:
259- `chatParticipantPrivate`: Private chat participant features
260- `languageModelSystem`: System messages for LM API
261- `chatProvider`: Custom chat provider implementation
262- `mappedEditsProvider`: Advanced editing capabilities
263- `inlineCompletionsAdditions`: Enhanced inline suggestions
264- `aiTextSearchProvider`: AI-powered search capabilities
265 
266### External Integrations
267- **GitHub**: Authentication and API access
268- **Azure**: Cloud services and experimentation
269- **OpenAI**: Language model API
270- **Anthropic**: Claude model integration - See **[src/extension/agents/claude/AGENTS.md](../src/extension/agents/claude/AGENTS.md)** for complete Claude Agent SDK integration documentation including architecture, components, and registries
271- **Telemetry**: Usage analytics and performance monitoring
272 
273## Development Workflow
274 
275### Setup and Build
276- `npm install`: Install dependencies
277- `npm run compile`: Development build
278- `npm run watch:*`: Various watch modes for development
279 
280### Updating Dependencies
281 
282**Anthropic SDK Packages:**
283When updating `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/sdk`, you **MUST** follow the upgrade guide in **[src/extension/agents/claude/AGENTS.md](../src/extension/agents/claude/AGENTS.md#upgrading-anthropic-sdk-packages)**. This includes:
2841. Reviewing changelogs for breaking changes
2852. Checking compilation errors in key Claude integration files
2863. Running through the testing checklist for core functionality, tools, hooks, and slash commands
287 
288### Testing
289- `npm run test:unit`: Unit tests
290- `npm run test:extension`: VS Code integration tests
291- `npm run simulate`: Scenario-based simulation tests
292 
293### Key Entry Points for Edits
294 
295**Chat & Conversation Features:**
296- **Adding new chat features**: Start in `src/extension/conversation/`
297- **Chat participants and agents**: Look in `src/extension/conversation/` for participant implementations
298- **Conversation storage**: Modify `src/extension/conversationStore/` for persistence features
299- **Inline chat improvements**: Look in `src/extension/inlineChat/` and `src/extension/inlineEdits/`
300 
301**Context & Intelligence:**
302- **Context resolution changes**: Check `src/extension/context/` and `src/extension/typescriptContext/`
303- **Prompt engineering**: Update `src/extension/prompts/` and `src/extension/prompt/`
304- **Intent detection**: Modify `src/extension/intents/` for user intent classification
305 
306**Search & Discovery:**
307- **Search functionality**: Update `src/extension/search/` for general search
308- **Workspace search**: Modify `src/extension/workspaceChunkSearch/` for large codebase search
309- **Semantic search**: Edit `src/extension/workspaceSemanticSearch/` for AI-powered search
310- **Workspace tracking**: Update `src/extension/workspaceRecorder/` for interaction recording
311 
312**Authentication & Configuration:**
313- **Authentication flows**: Modify `src/extension/authentication/` for GitHub integration
314- **Settings and config**: Update `src/extension/configuration/` and `src/extension/settingsSchema/`
315- **BYOK features**: Edit `src/extension/byok/` for custom API key functionality
316 
317**AI Integration:**
318- **AI endpoints**: Update `src/extension/endpoint/` for model selection and routing
319- **Language model tools**: Modify `src/extension/tools/` for AI tool integrations
320- **API abstractions**: Edit `src/extension/api/` for core interfaces
321- **MCP integration**: Update `src/extension/mcp/` for Model Context Protocol features
322 
323**User Interface:**
324- **VS Code commands**: Update `src/extension/commands/` for command implementations
325- **Code block rendering**: Modify `src/extension/codeBlocks/` for code display
326- **Onboarding flows**: Edit `src/extension/getting-started/` and `src/extension/onboardDebug/`
327- **Cross-tab features**: Update `src/extension/xtab/` for multi-tab coordination
328 
329**Testing & Development:**
330- **Test generation**: Modify `src/extension/testing/` for AI-powered test creation
331- **Extension tests**: Update `src/extension/test/` for extension-specific test utilities
332 
333**Platform Services:**
334- **Core platform services**: Extend `src/platform/` services for cross-cutting functionality
335- **VS Code integration**: Update contribution files and extension activation code
336- **Configuration**: Modify `package.json` contributions for VS Code integration
337 
338This extension is a complex, multi-layered system that provides comprehensive AI assistance within VS Code. Understanding the service architecture, contribution system, and separation between platform and extension layers is crucial for making effective changes.
339 
340## Best Practices
341- Use services and dependency injection over VS Code extension APIs when possible:
342  - Use `IFileSystemService` instead of Node's `fs` or `vscode.workspace.fs`
343  - Use `ILogService` instead of `console.log`
344  - Look for existing `I*Service` interfaces before reaching for raw APIs
345  - **Why**: Enables unit testing without VS Code host, supports simulation tests, provides cross-platform abstractions (Node vs web), and adds features like caching and size limits
346- Always use the URI type instead of using string file paths. There are many helpers available for working with URIs.
347