claudeCodeGuideAgent.ts
1 import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js' 2 import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js' 3 import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js' 4 import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js' 5 import { SEND_MESSAGE_TOOL_NAME } from 'src/tools/SendMessageTool/constants.js' 6 import { WEB_FETCH_TOOL_NAME } from 'src/tools/WebFetchTool/prompt.js' 7 import { WEB_SEARCH_TOOL_NAME } from 'src/tools/WebSearchTool/prompt.js' 8 import { isUsing3PServices } from 'src/utils/auth.js' 9 import { hasEmbeddedSearchTools } from 'src/utils/embeddedTools.js' 10 import { getSettings_DEPRECATED } from 'src/utils/settings/settings.js' 11 import { jsonStringify } from '../../../utils/slowOperations.js' 12 import type { 13 AgentDefinition, 14 BuiltInAgentDefinition, 15 } from '../loadAgentsDir.js' 16 17 const CLAUDE_CODE_DOCS_MAP_URL = 18 'https://code.claude.com/docs/en/claude_code_docs_map.md' 19 const CDP_DOCS_MAP_URL = 'https://platform.claude.com/llms.txt' 20 21 export const CLAUDE_CODE_GUIDE_AGENT_TYPE = 'claude-code-guide' 22 23 function getClaudeCodeGuideBasePrompt(): string { 24 // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the 25 // dedicated Glob/Grep tools, so point at find/grep instead. 26 const localSearchHint = hasEmbeddedSearchTools() 27 ? `${FILE_READ_TOOL_NAME}, \`find\`, and \`grep\`` 28 : `${FILE_READ_TOOL_NAME}, ${GLOB_TOOL_NAME}, and ${GREP_TOOL_NAME}` 29 30 return `You are the Claude guide agent. Your primary responsibility is helping users understand and use Claude Code, the Claude Agent SDK, and the Claude API (formerly the Anthropic API) effectively. 31 32 **Your expertise spans three domains:** 33 34 1. **Claude Code** (the CLI tool): Installation, configuration, hooks, skills, MCP servers, keyboard shortcuts, IDE integrations, settings, and workflows. 35 36 2. **Claude Agent SDK**: A framework for building custom AI agents based on Claude Code technology. Available for Node.js/TypeScript and Python. 37 38 3. **Claude API**: The Claude API (formerly known as the Anthropic API) for direct model interaction, tool use, and integrations. 39 40 **Documentation sources:** 41 42 - **Claude Code docs** (${CLAUDE_CODE_DOCS_MAP_URL}): Fetch this for questions about the Claude Code CLI tool, including: 43 - Installation, setup, and getting started 44 - Hooks (pre/post command execution) 45 - Custom skills 46 - MCP server configuration 47 - IDE integrations (VS Code, JetBrains) 48 - Settings files and configuration 49 - Keyboard shortcuts and hotkeys 50 - Subagents and plugins 51 - Sandboxing and security 52 53 - **Claude Agent SDK docs** (${CDP_DOCS_MAP_URL}): Fetch this for questions about building agents with the SDK, including: 54 - SDK overview and getting started (Python and TypeScript) 55 - Agent configuration + custom tools 56 - Session management and permissions 57 - MCP integration in agents 58 - Hosting and deployment 59 - Cost tracking and context management 60 Note: Agent SDK docs are part of the Claude API documentation at the same URL. 61 62 - **Claude API docs** (${CDP_DOCS_MAP_URL}): Fetch this for questions about the Claude API (formerly the Anthropic API), including: 63 - Messages API and streaming 64 - Tool use (function calling) and Anthropic-defined tools (computer use, code execution, web search, text editor, bash, programmatic tool calling, tool search tool, context editing, Files API, structured outputs) 65 - Vision, PDF support, and citations 66 - Extended thinking and structured outputs 67 - MCP connector for remote MCP servers 68 - Cloud provider integrations (Bedrock, Vertex AI, Foundry) 69 70 **Approach:** 71 1. Determine which domain the user's question falls into 72 2. Use ${WEB_FETCH_TOOL_NAME} to fetch the appropriate docs map 73 3. Identify the most relevant documentation URLs from the map 74 4. Fetch the specific documentation pages 75 5. Provide clear, actionable guidance based on official documentation 76 6. Use ${WEB_SEARCH_TOOL_NAME} if docs don't cover the topic 77 7. Reference local project files (CLAUDE.md, .claude/ directory) when relevant using ${localSearchHint} 78 79 **Guidelines:** 80 - Always prioritize official documentation over assumptions 81 - Keep responses concise and actionable 82 - Include specific examples or code snippets when helpful 83 - Reference exact documentation URLs in your responses 84 - Help users discover features by proactively suggesting related commands, shortcuts, or capabilities 85 86 Complete the user's request by providing accurate, documentation-based guidance.` 87 } 88 89 function getFeedbackGuideline(): string { 90 // For 3P services (Bedrock/Vertex/Foundry), /feedback command is disabled 91 // Direct users to the appropriate feedback channel instead 92 if (isUsing3PServices()) { 93 return `- When you cannot find an answer or the feature doesn't exist, direct the user to ${MACRO.ISSUES_EXPLAINER}` 94 } 95 return "- When you cannot find an answer or the feature doesn't exist, direct the user to use /feedback to report a feature request or bug" 96 } 97 98 export const CLAUDE_CODE_GUIDE_AGENT: BuiltInAgentDefinition = { 99 agentType: CLAUDE_CODE_GUIDE_AGENT_TYPE, 100 whenToUse: `Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can continue via ${SEND_MESSAGE_TOOL_NAME}.`, 101 // Ant-native builds: Glob/Grep tools are removed; use Bash (with embedded 102 // bfs/ugrep via find/grep aliases) for local file search instead. 103 tools: hasEmbeddedSearchTools() 104 ? [ 105 BASH_TOOL_NAME, 106 FILE_READ_TOOL_NAME, 107 WEB_FETCH_TOOL_NAME, 108 WEB_SEARCH_TOOL_NAME, 109 ] 110 : [ 111 GLOB_TOOL_NAME, 112 GREP_TOOL_NAME, 113 FILE_READ_TOOL_NAME, 114 WEB_FETCH_TOOL_NAME, 115 WEB_SEARCH_TOOL_NAME, 116 ], 117 source: 'built-in', 118 baseDir: 'built-in', 119 model: 'haiku', 120 permissionMode: 'dontAsk', 121 getSystemPrompt({ toolUseContext }) { 122 const commands = toolUseContext.options.commands 123 124 // Build context sections 125 const contextSections: string[] = [] 126 127 // 1. Custom skills 128 const customCommands = commands.filter(cmd => cmd.type === 'prompt') 129 if (customCommands.length > 0) { 130 const commandList = customCommands 131 .map(cmd => `- /${cmd.name}: ${cmd.description}`) 132 .join('\n') 133 contextSections.push( 134 `**Available custom skills in this project:**\n${commandList}`, 135 ) 136 } 137 138 // 2. Custom agents from .claude/agents/ 139 const customAgents = 140 toolUseContext.options.agentDefinitions.activeAgents.filter( 141 (a: AgentDefinition) => a.source !== 'built-in', 142 ) 143 if (customAgents.length > 0) { 144 const agentList = customAgents 145 .map((a: AgentDefinition) => `- ${a.agentType}: ${a.whenToUse}`) 146 .join('\n') 147 contextSections.push( 148 `**Available custom agents configured:**\n${agentList}`, 149 ) 150 } 151 152 // 3. MCP servers 153 const mcpClients = toolUseContext.options.mcpClients 154 if (mcpClients && mcpClients.length > 0) { 155 const mcpList = mcpClients 156 .map((client: { name: string }) => `- ${client.name}`) 157 .join('\n') 158 contextSections.push(`**Configured MCP servers:**\n${mcpList}`) 159 } 160 161 // 4. Plugin commands 162 const pluginCommands = commands.filter( 163 cmd => cmd.type === 'prompt' && cmd.source === 'plugin', 164 ) 165 if (pluginCommands.length > 0) { 166 const pluginList = pluginCommands 167 .map(cmd => `- /${cmd.name}: ${cmd.description}`) 168 .join('\n') 169 contextSections.push(`**Available plugin skills:**\n${pluginList}`) 170 } 171 172 // 5. User settings 173 const settings = getSettings_DEPRECATED() 174 if (Object.keys(settings).length > 0) { 175 // eslint-disable-next-line no-restricted-syntax -- human-facing UI, not tool_result 176 const settingsJson = jsonStringify(settings, null, 2) 177 contextSections.push( 178 `**User's settings.json:**\n\`\`\`json\n${settingsJson}\n\`\`\``, 179 ) 180 } 181 182 // Add the feedback guideline (conditional based on whether user is using 3P services) 183 const feedbackGuideline = getFeedbackGuideline() 184 const basePromptWithFeedback = `${getClaudeCodeGuideBasePrompt()} 185 ${feedbackGuideline}` 186 187 // If we have any context to add, append it to the base system prompt 188 if (contextSections.length > 0) { 189 return `${basePromptWithFeedback} 190 191 --- 192 193 # User's Current Configuration 194 195 The user has the following custom setup in their environment: 196 197 ${contextSections.join('\n\n')} 198 199 When answering questions, consider these configured features and proactively suggest them when relevant.` 200 } 201 202 // Return the base prompt if no context to add 203 return basePromptWithFeedback 204 }, 205 }