mirror of
https://github.com/microsoft/vscode.git
synced 2026-07-10 16:58:55 -05:00
Reorganize instruction files and document Claude agent registries (#3018)
* Initial plan * Reorganize instruction files for Claude agent integration - Add Claude agent integration section to copilot-instructions.md with reference to AGENTS.md - Simplify .claude/CLAUDE.md to reference copilot-instructions.md - Move SDK documentation from CLAUDE.md to AGENTS.md - Add comprehensive section on registries (hooks, slash commands, tool permissions) to AGENTS.md Co-authored-by: TylerLeonhardt <2644648+TylerLeonhardt@users.noreply.github.com> * Address PR feedback: add vscode-node handlers and simplify CLAUDE.md - Add VS Code-Node handlers section documenting askUserQuestionHandler - Remove unnecessary sentence from CLAUDE.md Co-authored-by: TylerLeonhardt <2644648+TylerLeonhardt@users.noreply.github.com> * Address PR feedback: add package.json info and reorganize Claude section - Add package.json command registration example for slash commands - Move Claude Agent Integration reference to External Integrations section for better organization Co-authored-by: TylerLeonhardt <2644648+TylerLeonhardt@users.noreply.github.com> * Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: TylerLeonhardt <2644648+TylerLeonhardt@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Copilot
@@ -1,35 +1,7 @@
|
||||
# Claude Agent SDK Documentation Index
|
||||
# Claude Instructions
|
||||
|
||||
## General Repository Instructions
|
||||
ALWAYS read [.github/copilot-instructions.md](../.github/copilot-instructions.md)
|
||||
|
||||
## Getting Started
|
||||
- [Overview](https://platform.claude.com/docs/en/agent-sdk/overview) - Learn about the Agent SDK architecture and core concepts
|
||||
- [Quickstart](https://platform.claude.com/docs/en/agent-sdk/quickstart) - Get up and running with your first agent in minutes
|
||||
For all repository instructions, coding standards, and development guidelines, **ALWAYS** read:
|
||||
|
||||
## Core SDK Implementation
|
||||
- [TypeScript](https://platform.claude.com/docs/en/agent-sdk/typescript) - Main TypeScript SDK reference for building agents
|
||||
- [TypeScript v2 Preview](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview) - Preview of upcoming v2 API with enhanced features
|
||||
- [Streaming vs Single Mode](https://platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode) - Choose between streaming responses or single-turn completions
|
||||
|
||||
## User Interaction & Control
|
||||
- [Permissions](https://platform.claude.com/docs/en/agent-sdk/permissions) - Control what actions Claude can take with user approval flows
|
||||
- [User Input](https://platform.claude.com/docs/en/agent-sdk/user-input) - Collect clarifications and decisions from users during execution
|
||||
- [Hooks](https://platform.claude.com/docs/en/agent-sdk/hooks) - Execute custom logic at key points in the agent lifecycle
|
||||
|
||||
## State & Session Management
|
||||
- [Sessions](https://platform.claude.com/docs/en/agent-sdk/sessions) - Manage conversation history and context across interactions
|
||||
- [File Checkpointing](https://platform.claude.com/docs/en/agent-sdk/file-checkpointing) - Save and restore file states for undo/redo functionality
|
||||
|
||||
## Advanced Features
|
||||
- [Structured Outputs](https://platform.claude.com/docs/en/agent-sdk/structured-outputs) - Get reliable JSON responses with schema validation
|
||||
- [Modifying System Prompts](https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts) - Customize Claude's behavior and instructions
|
||||
- [MCP](https://platform.claude.com/docs/en/agent-sdk/mcp) - Connect to Model Context Protocol servers for extended capabilities
|
||||
- [Custom Tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools) - Build your own tools to extend Claude's functionality
|
||||
|
||||
## Agent Composition & UX
|
||||
- [Subagents](https://platform.claude.com/docs/en/agent-sdk/subagents) - Compose complex workflows by delegating to specialized agents
|
||||
- [Slash Commands](https://platform.claude.com/docs/en/agent-sdk/slash-commands) - Add custom `/commands` for quick actions
|
||||
- [Skills](https://platform.claude.com/docs/en/agent-sdk/skills) - Package reusable agent capabilities as installable modules
|
||||
- [Todo Tracking](https://platform.claude.com/docs/en/agent-sdk/todo-tracking) - Help Claude manage and display task progress
|
||||
- [Plugins](https://platform.claude.com/docs/en/agent-sdk/plugins) - Extend the SDK with community-built integrations
|
||||
**[.github/copilot-instructions.md](../.github/copilot-instructions.md)**
|
||||
@@ -275,7 +275,7 @@ The extension uses numerous proposed VS Code APIs for advanced functionality:
|
||||
- **GitHub**: Authentication and API access
|
||||
- **Azure**: Cloud services and experimentation
|
||||
- **OpenAI**: Language model API
|
||||
- **Anthropic**: Claude model integration
|
||||
- **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
|
||||
- **Telemetry**: Usage analytics and performance monitoring
|
||||
|
||||
## Development Workflow
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This folder contains the Claude Code integration for VS Code Chat. It enables users to open a new Chat window and interact with a Claude Code instance directly within VS Code. **VS Code provides the UI, Claude Code provides the smarts.**
|
||||
|
||||
## Official Documentation
|
||||
## Official Claude Agent SDK Documentation
|
||||
|
||||
> **Important:** For the most up-to-date information on the Claude Agent SDK, always refer to the official documentation:
|
||||
>
|
||||
@@ -13,6 +13,39 @@ This folder contains the Claude Code integration for VS Code Chat. It enables us
|
||||
>
|
||||
> The SDK package is `@anthropic-ai/claude-agent-sdk`. The official documentation covers tools, hooks, subagents, MCP integration, permissions, sessions, and more.
|
||||
|
||||
### Core SDK Features
|
||||
|
||||
**Getting Started:**
|
||||
- [Overview](https://platform.claude.com/docs/en/agent-sdk/overview) - Learn about the Agent SDK architecture and core concepts
|
||||
- [Quickstart](https://platform.claude.com/docs/en/agent-sdk/quickstart) - Get up and running with your first agent in minutes
|
||||
|
||||
**Core SDK Implementation:**
|
||||
- [TypeScript](https://platform.claude.com/docs/en/agent-sdk/typescript) - Main TypeScript SDK reference for building agents
|
||||
- [TypeScript v2 Preview](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview) - Preview of upcoming v2 API with enhanced features
|
||||
- [Streaming vs Single Mode](https://platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode) - Choose between streaming responses or single-turn completions
|
||||
|
||||
**User Interaction & Control:**
|
||||
- [Permissions](https://platform.claude.com/docs/en/agent-sdk/permissions) - Control what actions Claude can take with user approval flows
|
||||
- [User Input](https://platform.claude.com/docs/en/agent-sdk/user-input) - Collect clarifications and decisions from users during execution
|
||||
- [Hooks](https://platform.claude.com/docs/en/agent-sdk/hooks) - Execute custom logic at key points in the agent lifecycle
|
||||
|
||||
**State & Session Management:**
|
||||
- [Sessions](https://platform.claude.com/docs/en/agent-sdk/sessions) - Manage conversation history and context across interactions
|
||||
- [File Checkpointing](https://platform.claude.com/docs/en/agent-sdk/file-checkpointing) - Save and restore file states for undo/redo functionality
|
||||
|
||||
**Advanced Features:**
|
||||
- [Structured Outputs](https://platform.claude.com/docs/en/agent-sdk/structured-outputs) - Get reliable JSON responses with schema validation
|
||||
- [Modifying System Prompts](https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts) - Customize Claude's behavior and instructions
|
||||
- [MCP](https://platform.claude.com/docs/en/agent-sdk/mcp) - Connect to Model Context Protocol servers for extended capabilities
|
||||
- [Custom Tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools) - Build your own tools to extend Claude's functionality
|
||||
|
||||
**Agent Composition & UX:**
|
||||
- [Subagents](https://platform.claude.com/docs/en/agent-sdk/subagents) - Compose complex workflows by delegating to specialized agents
|
||||
- [Slash Commands](https://platform.claude.com/docs/en/agent-sdk/slash-commands) - Add custom `/commands` for quick actions
|
||||
- [Skills](https://platform.claude.com/docs/en/agent-sdk/skills) - Package reusable agent capabilities as installable modules
|
||||
- [Todo Tracking](https://platform.claude.com/docs/en/agent-sdk/todo-tracking) - Help Claude manage and display task progress
|
||||
- [Plugins](https://platform.claude.com/docs/en/agent-sdk/plugins) - Extend the SDK with community-built integrations
|
||||
|
||||
## Overview
|
||||
|
||||
The Claude Code integration allows VS Code's chat interface to communicate with Claude Code, Anthropic's agentic coding assistant. When a user sends a message in a VS Code Chat window using this integration, the message is routed to a Claude Code session that can:
|
||||
@@ -144,6 +177,116 @@ Unit tests are located in `node/test/`:
|
||||
- `mockClaudeCodeSdkService.ts`: Mock SDK service for testing
|
||||
- `fixtures/`: Sample `.jsonl` session files for testing
|
||||
|
||||
## Extension Registries
|
||||
|
||||
The Claude integration uses several registries to organize and manage extensibility points:
|
||||
|
||||
### Hook Registry
|
||||
|
||||
**Location:** `node/hooks/claudeHookRegistry.ts`
|
||||
|
||||
The hook registry allows registering custom hooks that execute at key points in the agent lifecycle. Hooks are organized by `HookEvent` type from the Claude SDK.
|
||||
|
||||
**Key Features:**
|
||||
- Register handlers using `registerClaudeHook(hookEvent, ctor)`
|
||||
- Handlers are constructed via dependency injection using `IInstantiationService`
|
||||
- Hook instances are built from the registry and passed to the Claude SDK
|
||||
- Multiple handlers can be registered for the same event
|
||||
|
||||
**Example Hook Events:**
|
||||
- `'PreToolUse'` - Before a tool is executed
|
||||
- `'PostToolUse'` - After a tool completes
|
||||
- `'SubagentStart'` - When a subagent starts
|
||||
- `'SubagentEnd'` - When a subagent completes
|
||||
- `'SessionStart'` - When a session begins
|
||||
- `'SessionEnd'` - When a session ends
|
||||
|
||||
**Current Hook Handlers:**
|
||||
- `loggingHooks.ts` - Logging hooks for debugging and telemetry
|
||||
- `sessionHooks.ts` - Session lifecycle management
|
||||
- `subagentHooks.ts` - Subagent lifecycle tracking
|
||||
- `toolHooks.ts` - Tool execution tracking and processing
|
||||
|
||||
### Slash Command Registry
|
||||
|
||||
**Location:** `vscode-node/slashCommands/claudeSlashCommandRegistry.ts`
|
||||
|
||||
The slash command registry manages custom slash commands available in Claude chat sessions. Commands allow users to trigger specific functionality via `/commandname` syntax.
|
||||
|
||||
**Key Features:**
|
||||
- Register handlers using `registerClaudeSlashCommand(handler)`
|
||||
- Each handler implements `IClaudeSlashCommandHandler` interface
|
||||
- Commands can optionally register with VS Code Command Palette
|
||||
- Handlers receive arguments, response stream, and cancellation token
|
||||
|
||||
**Handler Interface:**
|
||||
```typescript
|
||||
interface IClaudeSlashCommandHandler {
|
||||
readonly commandName: string; // Command name (without /)
|
||||
readonly description: string; // Human-readable description
|
||||
readonly commandId?: string; // Optional VS Code command ID
|
||||
handle(args: string, stream: ChatResponseStream | undefined, token: CancellationToken): Promise<ChatResult | void>;
|
||||
}
|
||||
```
|
||||
|
||||
**Current Slash Commands:**
|
||||
- `/hooks` - Display information about registered hooks (from `hooksCommand.ts`)
|
||||
- `/memory` - Memory management commands (from `memoryCommand.ts`)
|
||||
|
||||
### Tool Permission Handlers
|
||||
|
||||
**Location:** `node/toolPermissionHandlers/` and `common/toolPermissionHandlers/`
|
||||
|
||||
Tool permission handlers control what actions Claude can take without user confirmation. They define the approval logic for various tool operations.
|
||||
|
||||
**Key Features:**
|
||||
- Auto-approve safe operations (e.g., file edits within workspace)
|
||||
- Request user confirmation for potentially dangerous operations
|
||||
- Handlers are organized by platform (common, node, vscode-node)
|
||||
|
||||
**Handler Types:**
|
||||
- **Common handlers** (`common/toolPermissionHandlers/`):
|
||||
- `bashToolHandler.ts` - Controls bash/shell command execution
|
||||
- `exitPlanModeHandler.ts` - Manages plan mode transitions
|
||||
|
||||
- **Node handlers** (`node/toolPermissionHandlers/`):
|
||||
- `editToolHandler.ts` - Handles file edit operations (Edit, Write, MultiEdit)
|
||||
|
||||
- **VS Code-Node handlers** (`vscode-node/toolPermissionHandlers/`):
|
||||
- `askUserQuestionHandler.ts` - Handles user question prompts via VS Code QuickPick UI
|
||||
|
||||
**Auto-approval Rules:**
|
||||
- File edits are auto-approved if the file is within the workspace
|
||||
- All other tools show a confirmation dialog via VS Code's chat API
|
||||
- User denials send appropriate messages back to Claude
|
||||
|
||||
**Extending the Registries:**
|
||||
|
||||
To add new functionality:
|
||||
|
||||
1. **New Hook Handler:**
|
||||
- Create a class implementing `HookCallbackMatcher`
|
||||
- Call `registerClaudeHook(hookEvent, YourHandler)` at module load time
|
||||
- Import your handler module in `node/hooks/index.ts`
|
||||
|
||||
2. **New Slash Command:**
|
||||
- Create a class implementing `IClaudeSlashCommandHandler`
|
||||
- Call `registerClaudeSlashCommand(YourHandler)` at module load time
|
||||
- Import your command module in `vscode-node/slashCommands/index.ts`
|
||||
- If providing a `commandId`, register the command in `package.json`:
|
||||
```json
|
||||
{
|
||||
"command": "copilot.claude.yourCommand",
|
||||
"title": "Your Command Title",
|
||||
"category": "Claude Agent"
|
||||
}
|
||||
```
|
||||
|
||||
3. **New Tool Permission Handler:**
|
||||
- Create handler in appropriate directory (common/node/vscode-node)
|
||||
- Implement tool approval logic
|
||||
- Import your handler module in `index.ts` to trigger registration
|
||||
|
||||
## Configuration
|
||||
|
||||
The integration respects VS Code settings:
|
||||
|
||||
Reference in New Issue
Block a user