|
| 1 | +--- |
| 2 | +title: About extensions for {% data variables.copilot.copilot_cli %} |
| 3 | +shortTitle: CLI extensions |
| 4 | +allowTitleToDifferFromFilename: true |
| 5 | +intro: 'Extensions let you add your own tools and slash commands to {% data variables.copilot.copilot_cli %}, using only the SDK that ships with the CLI.' |
| 6 | +product: '{% data reusables.gated-features.copilot-cli %}' |
| 7 | +versions: |
| 8 | + feature: copilot |
| 9 | +contentType: concepts |
| 10 | +category: |
| 11 | + - Learn about Copilot # Copilot discovery page |
| 12 | + - Learn about Copilot CLI # Copilot CLI bespoke page |
| 13 | +docsTeamMetrics: |
| 14 | + - copilot-cli |
| 15 | +--- |
| 16 | + |
| 17 | +{% data reusables.copilot.copilot-cli.cli-extensions-experimental %} |
| 18 | + |
| 19 | +An extension lets you add your own capabilities to {% data variables.copilot.copilot_cli_short %}. Each extension is a small Node.js module that runs as a separate process alongside your interactive session and connects back to it. Through that connection an extension can add: |
| 20 | + |
| 21 | +* **Tools** that {% data variables.product.prodname_copilot_short %} can call while it works on your behalf. |
| 22 | +* **Slash commands** that you run yourself. |
| 23 | + |
| 24 | +Because an extension runs real code on your machine, you can add capabilities the built-in tools don't have. For example, an extension can watch what happens in a session and keep a running total across tool calls, which a one-off shell command can't do. |
| 25 | + |
| 26 | +This article explains how extensions work and how {% data variables.copilot.copilot_cli_short %} handles them. For a hands-on guide to building your own extensions, see [AUTOTITLE](/copilot/tutorials/create-an-extension). |
| 27 | + |
| 28 | +> [!WARNING] |
| 29 | +> Extensions execute on your computer with your privileges. Only load extension code that you trust, in the same way you would only run any other script you didn't write yourself. |
| 30 | +
|
| 31 | +## How extensions are discovered |
| 32 | + |
| 33 | +When {% data variables.copilot.copilot_cli_short %} starts, it looks for extensions in several locations. Each extension lives in its own subdirectory, and that subdirectory must contain an entry file named `extension.mjs`, `extension.cjs`, or `extension.js`. These are all JavaScript files: the {% data variables.copilot.copilot_cli_short %} runs the entry file directly with Node.js, so an extension must be written in JavaScript—TypeScript and other languages are currently not supported. |
| 34 | + |
| 35 | +The name of the subdirectory becomes the name of the extension. |
| 36 | + |
| 37 | +| Source | Location | Availability | |
| 38 | +| --- | --- | --- | |
| 39 | +| **Project** | `.github/extensions/NAME/` in the current repository | Available to anyone working in that repository. | |
| 40 | +| **User** | `~/.copilot/extensions/NAME/` | Available in all your CLI sessions, in every directory. | |
| 41 | +| **Plugin** | An installed plugin | Available wherever the plugin is enabled. | |
| 42 | + |
| 43 | +## Choosing where an extension lives |
| 44 | + |
| 45 | +Where you put the extension directory determines who can use it: |
| 46 | + |
| 47 | +* Put it in **`.github/extensions/`** in a repository when the extension is specific to that project and you want to share it with everyone who works there. |
| 48 | +* Put it in **`~/.copilot/extensions/`** when you want the extension available in all of your own sessions, regardless of which directory you start the CLI in. |
| 49 | + |
| 50 | +The two locations follow exactly the same structure—a named subdirectory containing an `extension.mjs` file—so you can move an extension from one to the other simply by relocating its folder. |
| 51 | + |
| 52 | +## Enabling extensions |
| 53 | + |
| 54 | +Extensions are currently an experimental feature, so you need to turn on experimental features. You can do this by doing either of the following: |
| 55 | + |
| 56 | +* Start the CLI with the `--experimental` flag. |
| 57 | +* Run the `/experimental on` slash command inside an interactive session. |
| 58 | + |
| 59 | +## Changing how the CLI handles extensions |
| 60 | + |
| 61 | +You can limit {% data variables.product.prodname_copilot_short %}'s access to extensions, or turn them off entirely, by using the `/extensions mode` command. When you use this command you get three options: |
| 62 | + |
| 63 | +* **Load & Augment** (the default)—the CLI runs your extensions, _and_ {% data variables.product.prodname_copilot_short %} can manage them. |
| 64 | +* **Load Only**—the CLI runs your extensions, but {% data variables.product.prodname_copilot_short %} cannot manage them. |
| 65 | +* **Disabled**—extensions are turned off entirely in the current session and will remain disabled in future sessions until you switch to one of the other two settings. Other current sessions are not affected. |
| 66 | + |
| 67 | +Any change you make takes effect immediately in the current session: |
| 68 | + |
| 69 | +* Switching **to Disabled** stops any extensions that are currently running. Their processes are shut down and their tools are no longer available. |
| 70 | +* Switching **from Disabled** to either of the other settings starts your extensions. |
| 71 | +* Switching between **Load Only** and **Load & Augment** just changes whether {% data variables.product.prodname_copilot_short %} can manage your extensions. |
| 72 | + |
| 73 | +### What "managing extensions" means |
| 74 | + |
| 75 | +In **Load & Augment** mode, {% data variables.product.prodname_copilot_short %} is given a small set of extra tools that let it work on the extension system directly, as part of carrying out your requests. Using these tools, {% data variables.product.prodname_copilot_short %} can: |
| 76 | + |
| 77 | +* **List** the extensions it has discovered and see their status. |
| 78 | +* **Inspect** an extension, including a tail of its log file, to help diagnose one that has failed or is misbehaving. |
| 79 | +* **Scaffold** a new extension—generate a starter `extension.mjs` file for you to build on. |
| 80 | +* **Reload** extensions, so that code it (or you) has just written takes effect without restarting the session. |
| 81 | + |
| 82 | +This is what makes it possible for you to ask {% data variables.product.prodname_copilot_short %} to build an extension for you. {% data variables.product.prodname_copilot_short %} can create the file, write the code, and reload it, all without leaving the session. |
| 83 | + |
| 84 | +Choose **Load Only** when you want to keep a known, trusted set of extensions running but don't want {% data variables.product.prodname_copilot_short %} creating, reloading, or otherwise changing extension code—which runs on your machine—as a side effect of its work. Your existing extensions still run, and {% data variables.product.prodname_copilot_short %} can still call the tools they provide; it simply can't manage the extensions themselves. |
| 85 | + |
| 86 | +## Extensions compared with plugins |
| 87 | + |
| 88 | +Both extensions and plugins add functionality to {% data variables.copilot.copilot_cli_short %}, but they serve different purposes: |
| 89 | + |
| 90 | +* An **extension** is a single JavaScript module that you write to add tools and slash commands, backed by code that runs in your session. |
| 91 | +* A **plugin** is an installable package that bundles reusable components—such as agents, skills, hooks, and integrations—and can be distributed through a marketplace. |
| 92 | + |
| 93 | +For more information about plugins, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-cli-plugins). |
| 94 | + |
| 95 | +## Further reading |
| 96 | + |
| 97 | +* [AUTOTITLE](/copilot/tutorials/create-an-extension) |
| 98 | +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#slash-commands-in-the-interactive-interface) |
| 99 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli) |
0 commit comments