Appendix: Getting started reference material
Reference appendices for the Getting Started article — Unified Agent Architecture, deprecated settings, feature compatibility, BYOK models, legacy migration, and JetBrains support
Appendix: Getting started reference material
This file contains the reference appendices extracted from the Getting Started article. Each appendix provides detailed reference material for a specific topic covered in the main article.
📎 Appendix A: Unified Agent Architecture (v1.107+)
VS Code 1.107 introduced Agent HQ, a unified interface for managing agent sessions across local, background, and cloud execution contexts. This appendix provides detailed coverage of the architecture, workflows, and best practices.
Agent HQ Interface
Agent HQ provides a centralized view of all agent sessions:
- Recent Sessions List → View all local, background, and cloud sessions with filtering and search
- Session State Indicators → Read/unread markers, input-required flags, completion status
- Quick Actions → Archive, continue, copy workspace changes, delegate to different context
Session Types Comparison
+-----------------------------------------------------------------------------+
│ AGENT EXECUTION CONTEXTS │
+-----------------------------------------------------------------------------+
│ │
│ +-------------+ +-----------------+ +-------------------------+ │
│ │ LOCAL │ │ BACKGROUND │ │ CLOUD │ │
│ │ AGENT │ │ AGENT │ │ AGENT │ │
│ +-------------+ +-----------------+ +-------------------------+ │
│ │ Interactive │ │ Autonomous │ │ Async (GitHub) │ │
│ │ Same window │ │ Git work tree │ │ Creates PRs │ │
│ │ Blocks UI │ │ Non-blocking │ │ Team collaboration │ │
│ │ │ │ │ │ │ │
│ │ Best for: │ │ Best for: │ │ Best for: │ │
│ │ • Quick │ │ • Long tasks │ │ • Overnight work │ │
│ │ fixes │ │ • Parallel │ │ • Complex refactors │ │
│ │ • Iterative │ │ exploration │ │ • Team review │ │
│ │ work │ │ • Large changes │ │ │ │
│ +-------------+ +-----------------+ +-------------------------+ │
│ │
+-----------------------------------------------------------------------------+Work Tree Isolation Workflow
Background agents use Git work trees for complete isolation from your main workspace:
+------------------------------------------------------------------------------+
│ WORK TREE ISOLATION WORKFLOW │
+------------------------------------------------------------------------------+
│ │
│ 1. REQUEST │
│ +---------------------+ │
│ │ "Create background │ │
│ │ agent session" │ │
│ +---------------------+ │
│ │ │
│ │ │
│ 2. WORK TREE CREATION │
│ +-------------------------------------------------+ │
│ │ Git creates isolated work tree: │ │
│ │ /repo/.git/worktrees/agent-session-xyz/ │ │
│ │ │ │
│ │ • Full copy of current branch state │ │
│ │ • Independent staging area │ │
│ │ • No interference with main workspace │ │
│ +-------------------------------------------------+ │
│ │ │
│ │ │
│ 3. AGENT EXECUTION │
│ +-------------------------------------------------+ │
│ │ Agent works in isolated work tree: │ │
│ │ • Makes changes without affecting main │ │
│ │ • Can run tests, builds in isolation │ │
│ │ • Session visible in Agent HQ │ │
│ +-------------------------------------------------+ │
│ │ │
│ │ │
│ 4. REVIEW & INTEGRATE │
│ +-------------------------------------------------+ │
│ │ User reviews changes in Agent HQ: │ │
│ │ │ │
│ │ +-------------+ +-------------+ │ │
│ │ │ Direct │ │ Create PR │ │ │
│ │ │ Apply │ │ for Review │ │ │
│ │ +-------------+ +-------------+ │ │
│ │ │ │
│ │ Work tree cleaned up after integration │ │
│ +-------------------------------------------------+ │
│ │
+------------------------------------------------------------------------------+Work Tree Benefits
| Benefit | Description |
|---|---|
| No Conflicts | Agent changes don’t interfere with your local uncommitted work |
| Parallel Exploration | Run multiple agents exploring different approaches simultaneously |
| Safe Experimentation | Agent can make breaking changes without affecting your environment |
| SCM Integration | Changes appear in Source Control view with clear session attribution |
Enabling Work Trees
Work tree isolation is available via a dropdown when starting background sessions:
- Open Agent HQ or use “Continue in…” from chat
- Select “Background (Work Tree)” from the execution context dropdown
- Agent session starts in isolated work tree
- Review changes in Agent HQ → “Direct Apply” or “Create PR”
Planning → Agent Delegation
Plan mode integrates with agent delegation for seamless workflows:
+-------------------------------------------------------------------+
│ PLAN → DELEGATE WORKFLOW │
+-------------------------------------------------------------------+
│ │
│ 1. PLAN MODE │
│ +-------------------------------------------+ │
│ │ User: "Plan authentication refactoring" │ │
│ │ │ │
│ │ Copilot generates detailed plan: │ │
│ │ • Step 1: Extract auth middleware │ │
│ │ • Step 2: Create token service │ │
│ │ • Step 3: Update route handlers │ │
│ │ • Step 4: Add unit tests │ │
│ +-------------------------------------------+ │
│ │ │
│ │ │
│ 2. DELEGATION OPTIONS │
│ +-------------------------------------------+ │
│ │ +---------------------------------+ │ │
│ │ │ [Start Implementation] │ │ │
│ │ │ │ │ │
│ │ │ Execute as: │ │ │
│ │ │ │ Local Agent (interactive) │ │ │
│ │ │ │ Background Agent (work tree) │ │ │
│ │ │ │ Cloud Agent (GitHub PR) │ │ │
│ │ +---------------------------------+ │ │
│ +-------------------------------------------+ │
│ │
+-------------------------------------------------------------------+v1.107.1 Improvements
The v1.107.1 patch release added refinements to the agent experience:
| Improvement | Description |
|---|---|
| Side-by-Side View | Agent sessions view defaults to side-by-side layout for easier comparison |
| Input-Required Markers | Sessions requiring user input are clearly marked in Agent HQ |
| Workspace Copying | Support for copying workspace changes when creating background sessions |
| Persistent Chat Prompt | Chat prompt is not cleared when creating a new session |
| Collapsed Tool Calls | Tool calls in cloud sessions are collapsed by default for cleaner UI |
Entry Points for Delegation
You can delegate to different agent contexts from multiple entry points:
- Chat View → “Continue in…” button in chat response
- Agent HQ → Session actions menu → “Continue as…”
- Command Palette → “GitHub Copilot: Start Background Session”
- Untitled Prompt Files → “Continue in…” button when drafting prompts
📎 Appendix B: Deprecated VS Code Settings
The following settings are deprecated as of VS Code 1.102. Use .instructions.md files instead:
| Deprecated Setting | Migration |
|---|---|
github.copilot.chat.codeGeneration.instructions |
Use .github/instructions/*.instructions.md with applyTo patterns |
github.copilot.chat.testGeneration.instructions |
Use .github/instructions/*.instructions.md with applyTo patterns |
Recommendation: Remove these deprecated settings from your VS Code configuration and migrate to instruction files for better maintainability and version control.
📎 Appendix C: Feature Compatibility Matrix
Supported Files
| File Type | Location | Notes |
|---|---|---|
| Workspace instructions | .github/copilot-instructions.md |
Same as VS Code/Visual Studio |
| Global instructions | OS-specific path (see below) | Personal instructions across all projects |
| Prompt files | .github/prompts/*.prompt.md |
Invoked via /promptName commands |
Global Instructions Location
| OS | Path |
|---|---|
| Windows | %APPDATA%\JetBrains\<product><version>\copilot\global-copilot-instructions.md |
| macOS | ~/Library/Application Support/JetBrains/<product><version>/copilot/global-copilot-instructions.md |
| Linux | ~/.config/JetBrains/<product><version>/copilot/global-copilot-instructions.md |
Replace <product><version> with your IDE (e.g., IntelliJIdea2024.3, PyCharm2024.3).
Differences from VS Code
- JetBrains does not support
.agent.mdfiles (custom agents) - JetBrains does not support MCP server configuration
- Path-specific
.instructions.mdfiles work the same as VS Code - Prompt files use
/promptNamesyntax (same as VS Code)
📎 Appendix D: Bring-Your-Own-Key Model Management
VS Code 1.107 enhanced model management with the Language Models Editor and expanded bring-your-own-key (BYOK) support.
Language Models Editor
Access via Settings → GitHub Copilot → Language Models or Command Palette → “GitHub Copilot: Manage Language Models”
Features
| Feature | Description |
|---|---|
| Model Visibility | Hide unused models from the picker for a cleaner interface |
| Capability Filtering | Filter by vision support, tool calling, context window size |
| Provider Management | Add models from installed providers without leaving the editor |
| Search with Highlighting | Find models by name, provider, or capability |
Filter Syntax
| Filter | Description |
|---|---|
@provider:openai |
Show only OpenAI models |
@capability:vision |
Models with vision/image support |
@capability:tools |
Models with tool/function calling |
@visible:true/false |
Show visible or hidden models |
BYOK Providers
Bring-your-own-key allows using models from external providers with your own API keys:
| Provider | Models Available | Notes |
|---|---|---|
| Cerebras | Llama 3.3, DeepSeek v3.2, GLM-4.6 | Extremely fast inference |
| OpenRouter | 100+ models | Unified API for multiple providers |
| Ollama | Local models | Fully local, no API calls |
| Azure OpenAI | GPT-4o, GPT-4 Turbo | Enterprise deployment |
| Anthropic (direct) | Claude models | Direct API access |
Adding a BYOK Provider
- Open Command Palette → “GitHub Copilot: Add API Key”
- Select provider (Cerebras, OpenRouter, etc.)
- Enter your API key
- New models appear in the model picker
Model Capabilities Display
The model picker now shows capability indicators:
+----------------------------------------------------------+
│ Select Model │
+----------------------------------------------------------+
│ Claude Sonnet 4 [200K] [👁️] [🔧] │
│ GPT-4o [128K] [👁️] [🔧] │
│ DeepSeek v3.2 [64K] [🔧] │
│ Llama 3.3 70B [128K] [🔧] │
│ o3 [200K] [🔧] [💭] │
+----------------------------------------------------------+
│ Legend: [context] [👁️ vision] [🔧 tools] [💭 reasoning]│
+----------------------------------------------------------+HuggingFace Integration
The HuggingFace Inference Provider extension enables access to open-weights models:
Features
| Feature | Description |
|---|---|
| Multiple Inference Providers | HuggingFace Inference API, Nebius, SambaNova, Together AI, more |
| Fastest/Cheapest Mode | Automatic routing to optimal provider based on cost or speed |
| Open-Weights Models | Access to Llama, Mistral, DeepSeek, Qwen, and other open models |
Installation
- Install “HuggingFace for VS Code” extension from marketplace
- Sign in with HuggingFace account
- Models appear in Copilot’s model picker
- Select fastest/cheapest based on your preference
Extension ID
huggingface.huggingface-vscode
Quota Considerations
Important: BYOK models do not consume GitHub Copilot quota, but:
- Active Copilot subscription is still required
- Background query refinement (using GPT-4o Mini) doesn’t count against quota
- BYOK costs are billed directly by the provider
- Full prompt logging available in output channel for debugging/optimization
Claude Skills Support
VS Code 1.107 added support for Claude skills—reusable capability definitions that extend Claude’s abilities:
- Skills can be referenced in agent files via the
toolsfield - Skills provide specialized behaviors (web browsing, file analysis, etc.)
- Growing ecosystem of community and official skills
Last updated: December 2025
📎 Appendix E: Legacy .chatmode.md Migration
Prior to VS Code 1.106, custom agents were called “chat modes” and used different file conventions:
| Legacy | Current |
|---|---|
.chatmode.md extension |
.agent.md extension |
.github/chatmodes/ folder |
.github/agents/ folder |
Migration Steps
- VS Code automatically recognizes legacy
.chatmode.mdfiles - A Quick Fix action appears to migrate files to the new format
- Rename files from
*.chatmode.mdto*.agent.md - Move files from
.github/chatmodes/to.github/agents/
Recommendation: Migrate to the new format for consistency with current documentation and to ensure future compatibility.
📎 Appendix F: JetBrains IDE Support
JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support GitHub Copilot with their own conventions:
Supported Files
| File Type | Location | Notes |
|---|---|---|
| Workspace instructions | .github/copilot-instructions.md |
Same as VS Code/Visual Studio |
| Global instructions | OS-specific path (see below) | Personal instructions across all projects |
| Prompt files | .github/prompts/*.prompt.md |
Invoked via /promptName commands |
Global Instructions Location
| OS | Path |
|---|---|
| Windows | %APPDATA%\JetBrains\<product><version>\copilot\global-copilot-instructions.md |
| macOS | ~/Library/Application Support/JetBrains/<product><version>/copilot/global-copilot-instructions.md |
| Linux | ~/.config/JetBrains/<product><version>/copilot/global-copilot-instructions.md |
Replace <product><version> with your IDE (e.g., IntelliJIdea2024.3, PyCharm2024.3).
Differences from VS Code
- JetBrains does not support
.agent.mdfiles (custom agents) - JetBrains does not support MCP server configuration
- Path-specific
.instructions.mdfiles work the same as VS Code - Prompt files use
/promptNamesyntax (same as VS Code)