How Copilot understands your workspace
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. How Copilot understands your workspace View as Markdown Ask in VS Code Ask in VS Code Insiders Copilot agents use search and file-reading tools to find relevant workspace code.
For prompts like "where is authentication handled?" or "add tests for the list endpoint", they can gather context from related files instead of relying only on the current editor. What they find depends on available tools, indexing, exclusions, and the information you provide. Review their answers and edits against the source. This article explains the tools and indexes Copilot uses to discover workspace context, and the limits to consider when a result is incomplete.
An index helps find relevant snippets; it doesn't put the entire workspace into each model request. Search and read tools When you send a prompt, Copilot analyzes what information it needs and automatically selects the right combination of search tools to either answer your question or start generating code edits. Copilot runs multiple tools for this, reviews the results, and automatically performs follow-up searches until it has a good understanding of the problem.
For example, when asked to "add error handling to the payment service", the agent might: Use semantic search to find payment-related code across the project. Use grep to find existing error handling patterns in the codebase. Use usages to trace how the payment functions are called. Use file search to locate related configuration and test files. Read the relevant files and make coordinated changes. This iterative approach lets the agent follow relationships across the codebase.
It doesn't guarantee that every relevant file is found. Reference important files explicitly when you know they are needed. Agents have access to the following built-in search tools. You can also explicitly reference these tools in your prompts by typing # followed by the tool name. Tool Description Semantic search ( #codebase ) Finds code that matches the meaning of your question, not just exact keywords. Requires a workspace index .
Text search Searches file content for text matches, such as specific keywords. Grep Searches for exact text or regex patterns across files. Works without an index. File search Finds files by name or glob pattern. Usages Combines Find All References, Find Implementation, and Go to Definition to trace how symbols are used across files. List directory Lists the contents of a directory to explore the project structure. Read file Reads the content of a specific file to examine its code in detail.
These tools work for any workspace size. For small projects, the entire workspace can be read directly into the agent's context. For larger projects, the agent selects the most efficient search strategy based on your project size and available resources. Search GitHub repositories beyond your workspace In addition to searching the current workspace, agents can search code in other GitHub repositories. This is useful when the agent needs to learn about a codebase that is not open locally, for example to look up an API in an upstream library or compare an implementation across repositories.
Tool Description Semantic Search GitHub Repository ( #githubRepo ) Semantic search a GitHub repository for relevant source code snippets. Specify a repository using owner/repo . GitHub Text Search ( #githubTextSearch ) Text search a GitHub repository or organization for files containing specific keywords or code patterns. For more advanced GitHub workflows, such as searching and managing issues or pull requests, use the GitHub MCP server .
What the agent has access to Depending on the harness, tools, and context settings, agents can gather information from: Indexable workspace files , subject to indexing and exclusion rules Directory structure with nested folders and file names Code symbols and definitions (classes, functions, variables) Editor context , such as selected text, when included in the request Conversation history and previous tool results Important .gitignore is bypassed if you have a file open or have text selected within an ignored file.
Improve agent search with exclusion settings When an agent searches your workspace with text search or grep, every match returned becomes part of the conversation context, even if the agent never opens the file. Generated files, build artifacts, logs, and large datasets can produce many irrelevant matches that fill the context window with noise. Configure exclusion settings to keep agent searches focused on source code you care about: .gitignore : excludes files from text search, grep, and the semantic index . files.exclude Open in VS Code Open in VS Code Insiders : hides files from the Explorer and excludes them from text search, grep, and the semantic index. search.exclude Open in VS Code Open in VS Code Insiders : excludes files from text search and grep while keeping them visible in the Explorer.
Strict exclusions improve search relevance, speed up searches over large workspaces, and reduce the tokens consumed by search results. This also helps manage AI credit usage . Add exclusion patterns to your workspace settings . Patterns use glob syntax . Tip When a text search returns no results, the agent receives a hint that the pattern may be excluded, for example when investigating a dependency in node_modules . Semantic search The semantic search tool ( #codebase ) finds code by meaning rather than exact keywords.
Semantic search requires an index so that it can run quickly, even on very large codebases. Copilot maintains supported indexes automatically when indexing is available for your workspace. Availability depends on the repository host, your account's policies, and workspace settings. You can view the indexing status in the Copilot status dashboard in the VS Code Status Bar. Semantic index sources The index source determines availability and how quickly the index becomes available for the first time: GitHub repositories : GitHub indexes the GitHub repositories in your workspace.
Sign in with your GitHub account to use them. This index only needs to be built once per repository, which means it is often instantly available. GitHub builds and updates this index when needed. This is fast for small and medium sized projects, but might take some time if your repository contains hundreds of thousands of files. Remote indexing works for repositories hosted on GitHub.com or GitHub Enterprise Cloud. It is not supported for GitHub Enterprise Server.
Azure DevOps repositories : Indexes are automatically built and maintained. Sign in with your Microsoft account in VS Code for Copilot to start using the index. Check the Copilot Status Bar item for the current index status. Other workspaces : For local folders and repositories without a supported GitHub or Azure DevOps repository index, Copilot can use external ingest . This uploads indexable workspace files to GitHub to make them searchable.
It must be permitted by your account's policy and enabled for the workspace. See semantic indexing for non-GitHub repositories for availability and policy requirements. External ingest also helps search files and local changes that aren't covered by an existing repository index. If you see 'External ingest is disabled', follow the troubleshooting guidance . When indexing is available and enabled, run the Build Codebase Semantic Index command from the Command Palette to build or rebuild the index for the current workspace on demand.
What content is included in the semantic index VS Code indexes relevant text files that are part of your current project. This is not limited to specific file types or programming languages. VS Code automatically skips some common file types that ar
The rest of this page is on the live site.