AGENTS.md

1# Copilot CLI Integration
2 
3This folder contains the Copilot CLI integration for VS Code Chat. It enables users to open a new Chat window and interact with a Copilot CLI agent instance directly within VS Code. **VS Code provides the UI, Copilot CLI SDK provides the smarts.**
4 
5> **Important:** The Copilot CLI agent functionality is powered by the `@github/copilot/sdk` package. See the SDK package for full type definitions.
6 
7## Architecture
8 
9```
10┌─────────────────────────────────────────────────────────────────┐
11│                         VS Code Chat UI                          │
12└─────────────────────────┬───────────────────────────────────────┘
13                          │
14                          ▼
15┌─────────────────────────────────────────────────────────────────┐
16│                   CopilotCLISessionService                       │
17│  (node/copilotcliSessionService.ts)                              │
18│  - Manages SDK LocalSessionManager lifecycle                     │
19│  - Creates, retrieves, and caches CopilotCLISession instances    │
20│  - Handles session persistence, discovery, and forking           │
21│  - Monitors session files on disk for external changes           │
22│  - Installs OTel bridge span processor for debug panel           │
23└─────────────────────────┬───────────────────────────────────────┘
24                          │
25                          ▼
26┌─────────────────────────────────────────────────────────────────┐
27│                      CopilotCLISession                           │
28│  (node/copilotcliSession.ts)                                     │
29│  - Wraps a single SDK Session for one conversation               │
30│  - Processes SDK events (messages, tools, permissions, errors)   │
31│  - Handles tool confirmation and permission requests              │
32│  - Supports steering (injecting messages into running sessions)  │
33│  - Manages model switching and reasoning effort                  │
34│  - Tracks OTel spans for observability                           │
35└─────────────────────────┬───────────────────────────────────────┘
36                          │
37                          ▼
38┌─────────────────────────────────────────────────────────────────┐
39│                 Copilot CLI SDK (@github/copilot/sdk)            │
40│  - Manages the agentic conversation loop                         │
41│  - Executes tools and reports results via events                 │
42│  - Handles permissions (read, write, shell, MCP)                 │
43│  - Provides session persistence as events.jsonl files            │
44│  - Supports fleet mode and plan mode                             │
45└─────────────────────────────────────────────────────────────────┘
46                          │
47                          ▼
48┌─────────────────────────────────────────────────────────────────┐
49│                    MCP Server (In-Process)                        │
50│  (vscode-node/contribution.ts, vscode-node/inProcHttpServer.ts)  │
51│  - Provides VS Code-specific tools to the SDK via MCP protocol   │
52│  - Runs as an in-process HTTP server (InProcHttpServer)           │
53│  - Exposes diff, diagnostics, selection, and session tools        │
54│  - Discoverable by CLI via lock files in ~/.copilot/ide/          │
55└─────────────────────────────────────────────────────────────────┘
56```
57 
58## Folder Structure
59 
60The integration follows VS Code's platform layering pattern with three layers:
61 
62```
63copilotcli/
64├── common/                     # Platform-agnostic (NO Node.js or VS Code API imports)
65│   ├── copilotCLITools.ts      # Tool type definitions and processing helpers
66│   ├── copilotCLIPrompt.ts     # Prompt reference extraction and parsing
67│   ├── customSessionTitleService.ts
68│   ├── delegationSummaryService.ts
69│   ├── utils.ts                # SessionIdForCLI namespace (URI scheme: 'copilotcli')
70│   └── test/
71│
72├── node/                       # Node.js-specific (SDK integration, filesystem, permissions)
73│   ├── copilotCli.ts           # ICopilotCLISDK, CopilotCLIModels, CopilotCLIAgents
74│   ├── copilotcliSession.ts    # CopilotCLISession — main session wrapper
75│   ├── copilotcliSessionService.ts  # Session lifecycle management
76│   ├── permissionHelpers.ts    # Permission request handlers
77│   ├── copilotcliPromptResolver.ts  # Resolves prompts with variables and attachments
78│   ├── copilotCLISkills.ts     # Skills location resolution
79│   ├── copilotCLIImageSupport.ts    # Image attachment handling
80│   ├── mcpHandler.ts           # MCP server configuration for SDK sessions
81│   ├── nodePtyShim.ts          # Runtime node-pty copy for separate extension installs
82│   ├── userInputHelpers.ts     # User question/input handling interface
83│   ├── exitPlanModeHandler.ts  # Plan mode exit flow with user choice
84│   ├── ripgrepShim.ts          # Copies VS Code's ripgrep for SDK use
85│   └── test/
86│
87└── vscode-node/                # VS Code API-dependent (commands, MCP tools, UI)
88    ├── copilotCLIFolderMru.ts  # Folder MRU (most-recently-used) service
89    └── test/
90```
91 
92## Layering Rules
93 
94Strict import dependency rules — violations will cause build failures:
95 
96| Layer | Can import from | Cannot import from |
97|-------|----------------|--------------------|
98| `common/` | `src/util/common/`, `src/platform/`, sibling `../common/` | `node/`, `vscode-node/`, `vscode` module |
99| `node/` | `common/`, `src/util/`, `src/platform/`, Node.js builtins | `vscode-node/`, `vscode` module |
100| `vscode-node/` | `common/`, `node/`, `src/util/`, `src/platform/`, `vscode` module | (top layer — no restrictions) |
101 
102 
103## Key Components
104### `node/copilotCli.ts`
105 
106**ICopilotCLISDK / CopilotCLISDK**
107- Service interface wrapping the dynamic `import('@github/copilot/sdk')` for dependency injection and testability
108 
109**ICopilotCLIModels / CopilotCLIModels**
110- Fetches and caches available AI models from the SDK via `getAvailableModels()`
111- Registers a `LanguageModelChatProvider` with `targetChatSessionType: 'copilotcli'` so VS Code's model picker shows CLI models
112- Exposes model capabilities: vision support, reasoning effort levels, token limits, billing multiplier
113- Rebuilds model list on authentication changes
114- Builds configuration schema for reasoning effort per model (low/medium/high/xhigh)
115 
116**ICopilotCLIAgents / CopilotCLIAgents**
117- Discovers custom agents
118 
119### `node/copilotcliSession.ts`
120 
121**CopilotCLISession**
122- Wraps a single `Session` object from the `@github/copilot/sdk`
123- Entry point for every chat request via `handleRequest()`
124- Listens to SDK events and translates them to VS Code chat UI parts
125- Manages permission flow
126- Tracks external edits via `ExternalEditTracker` for proper diff display
127- Supports CLI commands: `compact`, `plan`, `fleet`
128- Built-in slash commands: `/commit`, `/sync`, `/merge`, `/create-pr`, `/create-draft-pr`, `/update-pr`
129- Captures pull request URLs from `create_pull_request` tool results
130 
131### `node/copilotcliSessionService.ts`
132 
133**ICopilotCLISessionService / CopilotCLISessionService**
134- Central service managing the lifecycle of all Copilot CLI sessions
135 
136### `common/copilotCLITools.ts`
137 
138Defines all tool type interfaces used by the Copilot CLI agent:
139 
140* File Operations
141* Shell Operations
142* Search Operations
143* Agent & Task Operations
144* User Interaction
145* Code Review & Git
146* Data, Memory & MCP
147* Security
148 
149 
150### `common/copilotCLIPrompt.ts`
151 
152Parses raw user prompts and extracts structured chat prompt references (files, locations, diagnostics)
153 
154### `node/copilotcliPromptResolver.ts`
155 
156**CopilotCLIPromptResolver**
157- Resolves chat request prompts by processing variable references and building attachments
158- Extracts prompt variables from `ChatVariablesCollection` (files, locations, diagnostics, custom instructions)
159- Converts image attachments
160- Generates the final user prompt
161- Handles workspace folder path translation for multi-folder isolation
162 
163### `node/permissionHelpers.ts`
164 
165Handles permission requests from the SDK. Each permission kind has a dedicated handler:
166 
167* handleReadPermission
168* handleWritePermission
169* handleShellPermission
170* handleMcpPermission
171* showInteractivePermissionPrompt
172 
173### `node/mcpHandler.ts`
174 
175**ICopilotCLIMCPHandler / CopilotCLIMCPHandler**
176- Loads MCP server configuration for SDK sessions
177- Proxies all VS Code-configured MCP servers through a gateway URL with `type: 'http'` config per server
178 
179### `node/copilotCLIImageSupport.ts`
180 
181**ICopilotCLIImageSupport / CopilotCLIImageSupport**
182- Stores image data as files in extension global storage (`copilot-cli-images/`)
183- Tracks trusted image URIs to auto-approve read permissions
184- Supports PNG, JPEG, GIF, WebP, and BMP formats via `isImageMimeType()`
185 
186### `node/exitPlanModeHandler.ts`
187 
188**`handleExitPlanMode()`**
189- Presents exit options when the SDK finishes plan generation: Autopilot, Interactive, Exit Only, Autopilot Fleet
190- Syncs saved plan changes back to the SDK session
191 
192### `node/cliHelpers.ts`
193 
194Path helpers for Copilot CLI directories.
195 
196## Message Flow
197 
1981. **User sends message** in VS Code Chat
1992. **CopilotCLISessionService** creates or retrieves an existing session wrapper
2003. **CopilotCLISession.handleRequest()** is called:
201   - If session is idle → normal request via `send()`
202   - If session is busy → steering request via `send({ mode: 'immediate' })`
2034. **SDK Session** processes the request and emits events:
204   - `assistant.message_delta` → streamed markdown to chat UI
205   - `tool.execution_start` / `tool.execution_complete` → tool invocation UI parts
206   - `permission.requested` → routed to permission handler (auto-approve or interactive)
207   - `user_input.requested` → question carousel shown to user
208   - `exit_plan_mode.requested` → plan mode exit choices
209   - `session.title_changed` → session title updated
210   - `subagent.started/completed/failed` → subagent metadata enriches tool invocations
211   - `hook.start/end` → forwarded to OTel bridge for debug panel
2125. **Session completes** — status set to `Completed`, usage reported
213 
214## Permission System
215 
216The SDK emits `permission.requested` events with a `kind` field.
217 
218When `autopilot` / `autoApprove` permission level is set, all permissions are auto-approved without user interaction.
219 
220Tool invocation messages are intentionally held in a queue (`toolCallWaitingForPermissions`) until the permission resolves, preventing a flash of "Running..." immediately followed by "Permission requested...".
221 
222## Session Persistence
223 
224Copilot CLI sessions are persisted to `~/.copilot/session-state/<sessionId>/` directories containing:
225- `events.jsonl` — Ordered event stream (messages, tool calls, results)
226- `workspace.yaml` — Workspace configuration
227 
228### `IWorkspaceInfo` (`../common/workspaceInfo.ts`)
229 
230Central type representing all workspace/repository/worktree state for a session:
231 
232### `IChatSessionMetadataStore` (`../common/chatSessionMetadataStore.ts`)
233 
234Persists VS Code-specific metadata that sits alongside the SDK's own session data. This metadata is **not part of the SDK's `events.jsonl`** — it tracks VS Code concepts like worktree properties, request-to-tool mappings, mode instructions, and checkpoint refs.
235 
236**Key Types:**
237 
238**`ChatSessionMetadataFile`** — The full metadata shape per session:
239 
240**`RequestDetails`** — Per-request metadata:
241 
242**`RepositoryProperties`** — Git repository metadata:
243 
244### `IChatSessionWorktreeService` (`../common/chatSessionWorktreeService.ts`)
245 
246Manages Git worktree lifecycle for session isolation. When isolation is enabled, each session gets its own Git worktree so the agent can make changes without affecting the user's working copy.
247 
248### `IChatSessionWorktreeCheckpointService` (`../common/chatSessionWorktreeCheckpointService.ts`)
249 
250Creates Git checkpoints (lightweight commits or refs) at the start and end of each request turn. These checkpoints enable the **undo/revert** feature — users can roll back to any previous turn's state.
251 
252### `IChatSessionWorkspaceFolderService` (`../common/chatSessionWorkspaceFolderService.ts`)
253 
254Handles workspace folder tracking for sessions **without** Git worktree isolation — i.e., when the agent works directly in the user's workspace. Used in multi-root workspaces where some folders may not have Git repositories.
255 
256### `IFolderRepositoryManager` (`../common/folderRepositoryManager.ts`)
257 
258Orchestrates the full folder/repository initialization flow for a session. This is the high-level coordinator that brings together worktree creation, trust verification, uncommitted change handling, and folder tracking.
259 
260### `ISessionRequestLifecycle` (`../vscode-node/sessionRequestLifecycle.ts`)
261 
262Orchestrates the start and end of each chat request turn, coordinating worktree commits, checkpoint creation, PR detection, and metadata updates. Handles the complexity of **steering** — where multiple requests can be in-flight for the same session simultaneously.
263 
264## Architecture Diagram: Shared Services
265 
266```
267┌──────────────────────────────────────────────────────────────────────┐
268│                    SessionRequestLifecycle                            │
269│  Orchestrates start/end of each request turn                         │
270│  Handles steering (multiple concurrent requests per session)         │
271└──────┬──────────┬──────────────┬─────────────┬──────────────────────┘
272       │          │              │             │
273       ▼          ▼              ▼             ▼
274┌────────────┐ ┌───────────┐ ┌─────────────┐ ┌──────────────────────┐
275│  Worktree  │ │ Workspace │ │ Checkpoint  │ │  MetadataStore       │
276│  Service   │ │  Folder   │ │  Service    │ │                      │
277│            │ │  Service  │ │             │ │ - Request details     │
278│ - Create   │ │           │ │ - Baseline  │ │ - Worktree props     │
279│ - Commit   │ │ - Track   │ │   checkpts  │ │ - Workspace folder   │
280│ - Cleanup  │ │ - Stage   │ │ - Post-turn │ │ - Repo properties    │
281│ - Archive  │ │ - Changes │ │   checkpts  │ │ - Mode instructions  │
282│ - Unarchive│ │ - Clear   │ │ - Multi-root│ │ - Checkpoint refs    │
283└────────────┘ └───────────┘ └─────────────┘ └──────────────────────┘
284       │          │              │             │
285       └──────────┴──────────────┴─────────────┘
286                         │
287                         ▼
288              ┌──────────────────────┐
289              │ FolderRepositoryMgr  │
290              │                      │
291              │ - Init flow          │
292              │ - Trust verification │
293              │ - Multi-root batch   │
294              │ - MRU tracking       │
295              │ - Isolation mode     │
296              └──────────────────────┘
297```
298 
299 
300## How to Add New Features
301 
302### Adding a new permission handler
303 
3041. Add `handle<Kind>Permission()` in `node/permissionHelpers.ts` following the existing pattern
3052. Add a `case '<kind>':` in the permission switch in `node/copilotcliSession.ts` (~line 468)
3063. Handler should return a `PermissionRequestResult` with `kind: 'approved' | 'denied-interactively-by-user' | ...`
307 
308### Handling a new SDK event
309 
3101. Add a listener in `node/copilotcliSession.ts` using `this._sdkSession.on(eventName, handler)`
3112. Wrap with `toDisposable()` and add to the `DisposableStore` for proper cleanup
3123. Use `this._stream?.markdown()` / `this._stream?.push()` to output to the chat UI
313 
314## Critical Pitfalls
315 
316- **Shims before SDK import**: For separate Marketplace/VSIX extension installs, `CopilotCLISDK.ensureShims()` in `node/copilotCli.ts` MUST run before any `import('@github/copilot/sdk')`. That runtime path calls both `ensureRipgrepShim()` and `ensureNodePtyShim()` to copy VS Code's native binaries from `envService.appRoot` into the installed extension's SDK layout.
317 
318- **Bundled/core shim path is different**: When Copilot Chat is bundled together with core VS Code, build-time packaging materializes only the ripgrep shim and writes `node_modules/@github/copilot/shims.txt`. That marker intentionally makes runtime `ensureShims()` return early, so node-pty is not copied in the bundled path; it is resolved from VS Code's own app tree instead.
319 
320- **Delayed permission UI**: Tool invocation messages are held in `toolCallWaitingForPermissions` until permission resolves. `flushPendingInvocationMessageForToolCallId()` flushes only the specific approved tool, not all pending tools. This is intentional — don't bypass it.
321 
322- **Steering mode**: When a session is already busy (`InProgress` or `NeedsInput`), use `send({ mode: 'immediate' })` to inject messages into the running conversation instead of starting a new request.
323 
324## Commands & Slash Commands
325 
326**Copilot CLI  commands** (user-facing, sent programmatically):
327- `compact` — compress conversation history to reduce tokens
328- `plan` — enter plan mode (SDK generates plan before executing)
329- `fleet` — start fleet mode for multi-agent parallel execution
330 
331**Built-in custom slash commands** (user-facing):
332`/commit`, `/sync`, `/merge`, `/create-pr`, `/create-draft-pr`, `/update-pr`
333 
334**VS Code Session commands** (registered via `registerCLIChatCommands` in `vscode-node/copilotCLIChatSessions.ts`):
335 
336## Configuration
337 
338The integration respects these VS Code settings (all under `github.copilot.chat.cli.*`):
339 
340| Setting | Default | Description |
341|---------|---------|-------------|
342| `mcp.enabled` | `true` | Enable MCP server proxying for CLI sessions |
343| `branchSupport.enabled` | `false` | Enable Git branch support features |
344| `showExternalSessions` | `false` | Show sessions created outside VS Code (e.g., terminal CLI) |
345| `planExitMode.enabled` | `true` | Show plan exit mode choices (Autopilot/Interactive/Exit) |
346| `planCommand.enabled` | `true` | Enable the `/plan` command |
347| `aiGenerateBranchNames.enabled` | `true` | AI-generated branch names for worktrees |
348| `forkSessions.enabled` | `true` | Allow forking sessions into new conversations |
349| `isolationOption.enabled` | `true` | Show worktree isolation option in session UI |
350| `autoCommit.enabled` | `true` | Auto-commit worktree changes at end of each turn |
351| `sessionController.enabled` | `false` | Use session controller API (V2) |
352| `thinkingEffort.enabled` | `true` | Show thinking effort control per model |
353| `sessionControllerForSessionsApp.enabled` | `false` | Use session controller for Sessions window |
354| `terminalLinks.enabled` | `true` | Enable terminal link detection |
355 
356## Dependencies
357 
358- `@github/copilot/sdk`: Official Copilot CLI SDK (session management, tools, permissions, events)
359 
360## Deprecated Code
361 
362V1 registration in `../vscode-node/copilotCLIChatSessionsContribution.ts` and `registerCopilotCLIServicesV1` are deprecated. All new development should use `CopilotCLISessionService` and the controller-based V2 API.
363