Chat View
Purpose and Scope
The Chat view is the code-first agent surface in Visual Studio Code. It is intended for work that stays centered on one workspace: prompt an agent, inspect changed files in the editor, validate the result with tasks or tests, and continue editing without switching away from the main window. The repository evidence for this page sits in the Copilot extension’s chat-session integrations. Those files show a split responsibility: VS Code owns the UI, workspace services, resource discovery, permission prompts, and session plumbing, while an external runtime such as Claude Code or Copilot CLI owns the agentic reasoning loop.
Sources: extensions/copilot/src/extension/chatSessions/claude/AGENTS.md, extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
The official user-facing distinction is that the Chat view is code-first, while the Agents window is agent-first; both can share sessions and settings. In source terms, that means the Chat view should be understood less as a single implementation file and more as a host surface for session targets. A session target contributes its own lifecycle, model handling, tool events, and persistence behavior, but it still has to integrate with VS Code concepts such as workspace folders, file resources, authentication, Git context, MCP, debug logging, and user approval boundaries.
Sources: extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts, extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
Relevant Source Files
- extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts - Defines the GitHub organization chat resource service used to choose an organization, poll for resource updates, validate cached instruction and agent files, and expose cached files as
vscode.ChatResourcevalues. - extensions/copilot/src/extension/chatSessions/claude/vscode-node/slashCommands/agentsCommand.ts - Implements and documents the Claude agents configuration wizard, including project and user agent locations, create and edit flows, YAML frontmatter, allowed tools, and model choices.
- extensions/copilot/src/extension/chatSessions/claude/AGENTS.md - Describes the Claude Code integration for VS Code Chat and names the supported SDK concepts: sessions, permissions, hooks, MCP integration, subagents, slash commands, skills, and checkpointing.
- extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts - Contains the Claude agent manager and imports the services that connect chat sessions to authentication, Git, MCP, OpenTelemetry, debug logging, workspace state, permissions, runtime data, and prompt resolution.
- extensions/copilot/src/extension/chatSessions/claude/vscode-node/toolPermissionHandlers/index.ts - Bridges VS Code node-side tool permission handlers into the Claude chat-session integration by importing the node permission handler package.
- extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md - Explains the Copilot CLI integration architecture, including the VS Code Chat UI, session service, session wrapper, SDK event loop, permission handling, in-process MCP server, persistence, model switching, and observability.
System-to-Code Mapping
A useful mental model for contributors is a layered stack. The visible Chat view sends user requests into a session service, the session service creates or resumes one conversation, and the session wrapper translates runtime events into editor-facing output, tool confirmations, errors, and telemetry. The Copilot CLI documentation makes this explicit: CopilotCLISessionService manages the SDK LocalSessionManager lifecycle, creates and caches CopilotCLISession instances, handles persistence and discovery, monitors session files on disk, and installs an OpenTelemetry bridge span processor for the debug panel.
Sources: extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
The Claude Code path expresses the same shape through code. ClaudeAgentManager owns a lazily started ClaudeLanguageModelServer and a disposable map of ClaudeCodeSession instances. Its imports are a concise map of the dependencies a Chat view session can require: IAuthenticationService, IGitService, IMcpService, IOTelService, IChatDebugFileLoggerService, IWorkspaceService, IClaudeRuntimeDataService, IClaudeSessionStateService, IClaudeToolPermissionService, and IClaudePlanFileTracker. This source-level wiring is what lets a prompt become a workspace-aware, observable, permission-governed agent interaction.
Sources: extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts
Resource discovery is another part of the mapping because the Chat view is expected to use project and organization context rather than static prompts. IGitHubOrgChatResourcesService returns a preferred organization for the current session, starts polling on a caller-provided interval, reads and writes cached prompt resources, clears caches, and lists cached files as chat resources. Its helper logic maps PromptsType.instructions to an instructions cache subdirectory and PromptsType.agent to an agents subdirectory, while validating file extensions before files are exposed.
Sources: extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts
Execution Flow
A typical Chat view interaction starts when the user opens Chat beside the editor and sends a prompt for the current project. The integration first resolves local state and reusable resources: workspace folders, Git and organization context, cached instructions, agent definitions, and any runtime configuration needed by the chosen session target. For Claude Code, the manager ensures that its language model server exists and has been started before the conversation needs it. Prompt resolution then turns the request into content blocks suitable for dispatch to the Claude agent runtime.
Sources: extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts, extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts
Once the runtime is active, the Chat view is no longer just displaying text. It is coordinating a stream of events that can include assistant messages, file edits, tool invocations, permission requests, errors, and telemetry spans. The Copilot CLI integration names these responsibilities directly on CopilotCLISession: it wraps one SDK session for one conversation, processes SDK events for messages, tools, permissions, and errors, supports steering by injecting messages into running sessions, manages model switching and reasoning effort, and tracks OpenTelemetry spans for observability.
Sources: extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
Permission flow is the safety boundary in that event stream. The Copilot CLI SDK is described as handling permissions for read, write, shell, and MCP actions, and the session wrapper handles tool confirmation and permission requests. The Claude path imports IClaudeToolPermissionService, and the VS Code node permission handler entry point imports the node handler package into the chat-session integration. In practice, that means tool use should be treated as a first-class session event, not as an invisible side effect of a model response.
Sources: extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts, extensions/copilot/src/extension/chatSessions/claude/vscode-node/toolPermissionHandlers/index.ts, extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
API Components and Configuration Reference
The following compact reference lists the concrete source-level contracts and configuration fields visible in the supplied files. Use it when tracing Chat view behavior from UI expectations to extension code. The exact UI commands and menu labels are documented in product docs, while these repository files show how session targets, cached resources, subagents, models, and permissions are represented in the Copilot extension source.
| Component | Source-level contract | Chat view role |
|---|---|---|
| `IGitHubOrgChatResourcesService.getPreferredOrganizationName(): Promise<string | undefined>` | Returns the organization for the current session. |
startPolling(intervalMs: number, callback: (orgName: string) => Promise<void>): IDisposable | Creates a disposable polling subscription with a custom interval. | Lets resource providers refresh organization instructions or agent files. |
| `readCacheFile(type: PromptsType, orgName: string, filename: string): Promise<string | undefined>` | Reads one cached instruction or agent resource. |
writeCacheFile(type: PromptsType, orgName: string, filename: string, content: string, options?: { checkForChanges?: boolean }): Promise<boolean> | Writes cache content and can report whether it changed. | Updates organization chat resources without unnecessary churn. |
clearCache(type: PromptsType, orgName: string, exclude?: Set<string>): Promise<void> | Deletes cached resources, optionally preserving selected filenames. | Keeps local chat resource state aligned with upstream resources. |
listCachedFiles(type: PromptsType, orgName: string): Promise<vscode.ChatResource[]> | Lists validated cached files as VS Code chat resources. | Exposes prompt and agent resources to the Chat view. |
| Claude agent file frontmatter | name, description, model, optional allowedTools, followed by system prompt markdown. | Defines reusable specialized subagents that can be delegated to from chat. |
| Claude model ids | sonnet, opus, haiku, inherit. | Lets a subagent choose balanced, more capable, faster, or parent-inherited model behavior. |
| Copilot CLI session wrapper | Processes messages, tools, permissions, errors, steering, model switching, reasoning effort, and OTel spans. | Converts SDK agent events into Chat view session behavior. |
Sources: extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts, extensions/copilot/src/extension/chatSessions/claude/vscode-node/slashCommands/agentsCommand.ts, extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
The Claude agents wizard is the clearest source for model configuration in this page’s evidence. It supports project agents under .claude/agents/ and personal agents under ~/.claude/agents/. The create flow can either generate an agent with Claude from a natural-language description or use manual configuration where the user supplies an identifier, system prompt, description, tools, and model. Existing agents can be viewed, edited, deleted with confirmation, or reopened in the editor, which makes specialized Chat view behavior reviewable as ordinary files.
Sources: extensions/copilot/src/extension/chatSessions/claude/vscode-node/slashCommands/agentsCommand.ts
Disabled States, Debugging, and Operational Signals
The supplied sources do not show one global disabled-state flag for the Chat view. Instead, they show several gates that can make an experience unavailable or limited. Organization resources must use a supported PromptsType and match the expected file extension. A Claude session must be able to initialize its language model server and runtime services. MCP, Git, authentication, workspace state, runtime data, and permission services all participate in whether a session can gather context or perform an action. This distributed gating is typical for an editor-integrated agent surface.
Sources: extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts, extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts
For debugging, the code points to both event logs and request-level telemetry. The Claude manager imports IChatDebugFileLoggerService, IOTelService, TraceContext, SpanStatusCode, deriveClaudeOTelEnv, extractToolParameters, and ClaudeOTelTracker. The Copilot CLI integration says the session service installs an OpenTelemetry bridge span processor for the debug panel and that sessions track spans while processing SDK events. When a Chat view interaction fails, inspect the target session path: resource selection, prompt dispatch, permission handling, SDK events, MCP tools, and telemetry are separate diagnostic layers.
Sources: extensions/copilot/src/extension/chatSessions/claude/node/claudeCodeAgent.ts, extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md
Next Steps
When extending or troubleshooting Chat view behavior, first identify the session target. For Claude Code, start with the Claude integration guide, the agent manager, and the agents slash-command wizard because they define the SDK boundary, model choices, subagent files, prompt resolution, permissions, MCP, and telemetry wiring. For Copilot CLI, follow the documented path from the VS Code Chat UI to CopilotCLISessionService, CopilotCLISession, the @github/copilot/sdk event loop, and the in-process MCP server. For shared organization resources, inspect IGitHubOrgChatResourcesService before changing how prompt files appear in chat.
Sources: extensions/copilot/src/extension/chatSessions/claude/AGENTS.md, extensions/copilot/src/extension/chatSessions/claude/vscode-node/slashCommands/agentsCommand.ts, extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md, extensions/copilot/src/extension/agents/vscode-node/githubOrgChatResourcesService.ts