|
| 1 | +--- |
| 2 | +title: Researching with {% data variables.copilot.copilot_cli %} |
| 3 | +shortTitle: Researching with {% data variables.product.prodname_copilot_short %} |
| 4 | +allowTitleToDifferFromFilename: true |
| 5 | +intro: 'The `/research` slash command turns {% data variables.product.prodname_copilot_short %} into your research assistant, gathering in-depth information and insights on a topic.' |
| 6 | +versions: |
| 7 | + feature: copilot |
| 8 | +topics: |
| 9 | + - CLI |
| 10 | +contentType: concepts |
| 11 | +category: |
| 12 | + - Learn about Copilot # Copilot discovery page |
| 13 | + - Learn about Copilot CLI # Copilot CLI bespoke page |
| 14 | +--- |
| 15 | + |
| 16 | +## Introduction |
| 17 | + |
| 18 | +{% data variables.copilot.copilot_cli_short %}'s `/research` slash command is a powerful tool for deep research and investigation. When you enter `/research` followed by details of what you want to know about, {% data variables.product.prodname_copilot_short %} activates a specialized research agent that gathers and processes information from your codebase, from relevant {% data variables.product.github %} repositories, and from the web. This built-in custom agent produces a comprehensive Markdown report with citations, along with a brief summary in the CLI. You can view the full report and save it as a gist on {% data variables.product.github %}, making it easy to share. |
| 19 | + |
| 20 | +The command is designed to provide exhaustive, well-cited answers to complex questions about codebases, APIs, libraries, software architecture and other technical topics. |
| 21 | + |
| 22 | +## Using the `/research` slash command |
| 23 | + |
| 24 | +In an interactive CLI session, enter: |
| 25 | + |
| 26 | +```copilot copy |
| 27 | +/research TOPIC |
| 28 | +``` |
| 29 | + |
| 30 | +Where `TOPIC` is a natural language description of what you want to find out about. |
| 31 | + |
| 32 | +Depending on the permissions you have given the CLI, {% data variables.product.prodname_copilot_short %} may ask you to grant permission for it to create a directory in which to store data as it compiles the research. |
| 33 | + |
| 34 | +When the research is complete, {% data variables.product.prodname_copilot_short %} shows you a summary of the key findings, and gives you a link to a Markdown file containing the full report. |
| 35 | + |
| 36 | +## Viewing and sharing a research report |
| 37 | + |
| 38 | +You can use the link displayed when the research completes to view the full report in your default editor for Markdown files. |
| 39 | + |
| 40 | +Alternatively, press <kbd>Ctrl</kbd>+<kbd>Y</kbd> to open the current session's most recent research report in the terminal. |
| 41 | + |
| 42 | +> [!NOTE] |
| 43 | +> The application used to display a report when you press <kbd>Ctrl</kbd>+<kbd>Y</kbd> is determined by the value of the `COPILOT_EDITOR`, `VISUAL`, or `EDITOR` environment variables (in that order of precedence). If none of these are set, the CLI will use vi on Linux or vim on macOS. |
| 44 | +
|
| 45 | +To share the report you can either save it to a file or create a {% data variables.product.github %} gist. |
| 46 | + |
| 47 | +1. To create a gist enter: |
| 48 | + |
| 49 | + ```copilot copy |
| 50 | + /share gist research |
| 51 | + ``` |
| 52 | + |
| 53 | + To save to a file, enter: |
| 54 | + |
| 55 | + ```copilot copy |
| 56 | + /share file research [PATH] |
| 57 | + ``` |
| 58 | + |
| 59 | + If you omit the `[PATH]` parameter, the file will be saved to the current working directory with a filename based on the research topic. |
| 60 | + |
| 61 | +1. Use the up/down and enter keys to select the report you want to share from the list of research reports you've created during the current session. |
| 62 | + |
| 63 | + The URL of the gist, or the path to the file, is displayed in the CLI. |
| 64 | + |
| 65 | +## Benefits of `/research` |
| 66 | + |
| 67 | +* **Depth over speed**: Normal chat is optimized for quick answers. `/research` is optimized for thoroughness. It produces reports that can be hundreds of lines long, with architecture diagrams, code snippets, and citations. |
| 68 | + |
| 69 | +* **Saved and shareable output**: Reports are saved to disk as Markdown files. You can view and share them at any time. This makes the research output a permanent artifact, rather than a transient chat message. |
| 70 | + |
| 71 | +* **Works across repositories**: When logged into {% data variables.product.github %}, the agent can search across your organization's repositories, fetch files from any public or accessible private repository, and search the web—it's not limited to your local codebase. |
| 72 | + |
| 73 | +* **Query-type adaptation**: Rather than generating a standard, one-size-fits-all report, the response format automatically adapts to whether you're asking a how-to question, a conceptual question, or requesting a technical deep-dive. |
| 74 | + |
| 75 | +* **Autonomous operation**: The agent never interrupts you with clarifying questions. It makes reasonable assumptions and explicitly documents them in a "Confidence Assessment" section. |
| 76 | + |
| 77 | +## Example prompts for `/research` |
| 78 | + |
| 79 | +### Codebase architecture |
| 80 | + |
| 81 | +```copilot copy |
| 82 | +/research What is the architecture of this codebase? |
| 83 | +``` |
| 84 | + |
| 85 | +**Why it works well**: The research agent has access to `grep`, `glob`, and `view` tools scoped to your current working directory. It can explore the full project tree, read key files, and synthesize an architectural overview—something a normal chat response might do only superficially. The agent will typically produce architecture diagrams, component breakdowns, and data flow descriptions. |
| 86 | + |
| 87 | +### How a specific technology works |
| 88 | + |
| 89 | +```copilot copy |
| 90 | +/research How does React implement concurrent rendering? |
| 91 | +``` |
| 92 | + |
| 93 | +**Why it works well**: The agent uses specialized tools to pull information from the internet, and to look at actual React source code on {% data variables.product.github %}. It's instructed to prioritize code over documentation and provide file paths with line numbers. |
| 94 | + |
| 95 | +### Understanding internal implementation patterns |
| 96 | + |
| 97 | +```copilot copy |
| 98 | +/research How are feature flags implemented at our organization? |
| 99 | +``` |
| 100 | + |
| 101 | +**Why it works well**: The agent is explicitly instructed to "always prioritize internal/private implementations over public/open-source alternatives" and to search the organization's repositories first using `org:ORGNAME` queries. It knows to look for internal naming patterns like `-hub`, `-service`, `-client`. |
| 102 | + |
| 103 | +### Comparing technologies or approaches |
| 104 | + |
| 105 | +```copilot copy |
| 106 | +/research What's the difference between JWT and session-based authentication? |
| 107 | +``` |
| 108 | + |
| 109 | +**Why it works well**: The agent adapts its response to "Conceptual/Explanatory Questions" with narrative explanations, trade-offs, and design decisions. It will typically use tables for comparisons of three or more items. |
| 110 | + |
| 111 | +### Process/how-to questions |
| 112 | + |
| 113 | +```copilot copy |
| 114 | +/research How do I add an endpoint to the API? |
| 115 | +``` |
| 116 | + |
| 117 | +**Why it works well**: The agent is trained to detect query type and provide step-by-step guidance with links to relevant docs, contacts, and systems for process/how-to type questions. |
| 118 | + |
| 119 | +### Deep-diving into a specific codebase component |
| 120 | + |
| 121 | +```copilot copy |
| 122 | +/research How is the session management system implemented in this repo? |
| 123 | +``` |
| 124 | + |
| 125 | +**Why it works well**: Combining local tools (`grep`, `glob`, `view`) with the agent's instructions to "trace imports, calls, and type references" and "follow dependencies" means it will walk through the actual implementation, not just give a high-level answer. |
| 126 | + |
| 127 | +## When you might _not_ want to use `/research` |
| 128 | + |
| 129 | +* **Quick, simple questions**: If you just want to know "What does this function do?" or "Fix this bug", a normal chat message is faster and more appropriate. `/research` is designed for questions requiring extensive investigation. |
| 130 | + |
| 131 | +* **When you need code changes**: `/research` produces a report, not code modifications. It uses the `create` tool to save the report file, but does not use `edit`, `bash`, or other code-modification tools. If you need the agent to actually change your code, use a normal prompt (typically starting in plan mode). |
| 132 | + |
| 133 | +* **Time-sensitive interactions**: Research takes longer than a normal response because the agent makes many tool calls (searching code, fetching files, searching the web). If you need a quick answer in the flow of coding, normal chat is better. |
| 134 | + |
| 135 | +## Considerations and things to be aware of |
| 136 | + |
| 137 | +* **Reports are tied to your session**: Research reports are stored in a session-specific research directory. If you start a new session, previous research won't be available within the CLI when you use the <kbd>Ctrl</kbd>+<kbd>Y</kbd> shortcut or the `/share` slash command. However, you can access previous reports from the appropriate `~/.copilot/session-state/SESSION-ID/research/` directory. |
| 138 | + |
| 139 | + In Linux or macOS, you can use the following command at a terminal command prompt to list the 10 most recent CLI session directories: |
| 140 | + |
| 141 | + ```bash copy |
| 142 | + ls -dtl ~/.copilot/session-state/*/ | head -10 |
| 143 | + ``` |
| 144 | + |
| 145 | +* **The research agent uses a specific model**: The research agent is hard-coded to use a particular AI model (see [AUTOTITLE](/copilot/reference/cli-command-reference#built-in-agents)). The model selection is not configurable via the `/model` command. The research agent always uses the defined model regardless of what model you've selected for your main session. |
| 146 | + |
| 147 | +* **Report quality varies by query type**: The agent classifies your query into three types and adapts its response accordingly: |
| 148 | + |
| 149 | + * **Process questions** → step-by-step guidance (minimal code). |
| 150 | + * **Conceptual questions** → narrative explanation with context. |
| 151 | + * **Technical deep-dives** → full architecture diagrams, component sections, and code examples. |
| 152 | + |
| 153 | + The way you phrase your prompt may affect the agent's choice of research classification. For example, if you want a technical deep-dive but you phrase your question as "What is X?", you might get a conceptual answer. In this situation you could rephrase your prompt to be more explicit about the type of report you want {% data variables.product.prodname_copilot_short %} to produce. For example: "Give me a technical deep-dive into X, with architecture diagrams and code examples." |
| 154 | + |
| 155 | +## Further reading |
| 156 | + |
| 157 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli) |
| 158 | +* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/use-copilot-cli) |
0 commit comments