From 7f3e8ea133644ba63206fcaf4cef3ed2fba8f882 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 23 Sep 2026 01:25:53 +0000 Subject: [PATCH] chore: publish from main --- .../workflows/learning-hub-updater.lock.yml | 2 +- .github/workflows/learning-hub-updater.md | 16 +- .../learning-hub/automating-with-hooks.md | 39 ++-- .../learning-hub/building-custom-agents.md | 16 +- .../copilot-configuration-basics.md | 170 +++++++++--------- .../installing-and-using-plugins.md | 35 ++-- .../learning-hub/understanding-mcp-servers.md | 22 +-- 7 files changed, 163 insertions(+), 137 deletions(-) diff --git a/.github/workflows/learning-hub-updater.lock.yml b/.github/workflows/learning-hub-updater.lock.yml index 8adca60c..f5d3ccbe 100644 --- a/.github/workflows/learning-hub-updater.lock.yml +++ b/.github/workflows/learning-hub-updater.lock.yml @@ -1,4 +1,4 @@ -# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"71be7bf13cd61ce7e5d48a2d2e5978e9be648bdc956d1684b2da2bca4cad11e0","body_hash":"173edcea3d4067513e6b172ab889f21a07bfa9181d38c1dfcc79617a2fa98019","compiler_version":"v0.86.2","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.79"}} +# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"71be7bf13cd61ce7e5d48a2d2e5978e9be648bdc956d1684b2da2bca4cad11e0","body_hash":"43a4718bf818e0555b685c7a173049713a294828b0753c1fa7378a3ad47120e6","compiler_version":"v0.86.2","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.79"}} # gh-aw-manifest: {"version":1,"secrets":["GH_AW_CI_TRIGGER_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/cache/restore","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/cache/save","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/checkout","sha":"3d3c42e5aac5ba805825da76410c181273ba90b1","version":"v7.0.1"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"820762786026740c76f36085b0efc47a31fe5020","version":"v7.0.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"6aab9e5b5c91c615506061f09bedd81a23babe3c","version":"v0.86.2"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.44","digest":"sha256:0d727725c737b58c7bdf51f640cffb928385ec46517e0917c7f1a02f1bada8b4","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.44@sha256:0d727725c737b58c7bdf51f640cffb928385ec46517e0917c7f1a02f1bada8b4"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.44","digest":"sha256:b50fbadba138f6e9aba94aca09711335c489bb3b15861220cb66f6092e042dc7","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.44@sha256:b50fbadba138f6e9aba94aca09711335c489bb3b15861220cb66f6092e042dc7"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.44","digest":"sha256:83e48bbe12c634be8c228a576832fe45f66c529ac3659db92bddbcf2eeb6d627","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.44@sha256:83e48bbe12c634be8c228a576832fe45f66c529ac3659db92bddbcf2eeb6d627"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.4.9","digest":"sha256:e5a1569aeaf41820fa7bdee3e94468cae448133cdbf00119ad24f5b74db1ab9f","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.4.9@sha256:e5a1569aeaf41820fa7bdee3e94468cae448133cdbf00119ad24f5b74db1ab9f"},{"image":"ghcr.io/github/gh-aw-node","digest":"sha256:0d9f1fb5fd6610c0ac1f5194a38e45a8a1e81f8a390d5142d8e4e6f26a4b3196","pinned_image":"ghcr.io/github/gh-aw-node@sha256:0d9f1fb5fd6610c0ac1f5194a38e45a8a1e81f8a390d5142d8e4e6f26a4b3196"},{"image":"ghcr.io/github/github-mcp-server:v1.9.0","digest":"sha256:881b53d6f75f69bdbc1b5b10fc2f1361717c19054143b3a8529fb5c32061a50e","pinned_image":"ghcr.io/github/github-mcp-server:v1.9.0@sha256:881b53d6f75f69bdbc1b5b10fc2f1361717c19054143b3a8529fb5c32061a50e"}]} # This file was automatically generated by gh-aw (v0.86.2). DO NOT EDIT. To debug this workflow, load the skill at https://github.com/github/gh-aw/blob/main/debug.md # diff --git a/.github/workflows/learning-hub-updater.md b/.github/workflows/learning-hub-updater.md index a40d2de6..c944f70f 100644 --- a/.github/workflows/learning-hub-updater.md +++ b/.github/workflows/learning-hub-updater.md @@ -58,6 +58,7 @@ Identify: - **Missing features** — new capabilities not yet documented - **Outdated information** — features that have been renamed, deprecated, or significantly changed - **Missing links** — new official docs or blog posts not in the Further Reading section +- **Stale version notes** — inline `vX.Y.Z+` callouts, "previously"/"as of"/"breaking change" notes, or superseded feature descriptions that are candidates for consolidation or removal now that a newer release has landed If there is nothing new or everything is already up to date, stop here and report that no updates are needed. @@ -65,6 +66,18 @@ If there is nothing new or everything is already up to date, stop here and repor If updates are needed, make a decision on whether a new page needs to be added (e.g., for a major new feature) or if existing pages can be updated with new sections. +**Content model — read this before editing.** The Learning Hub distinguishes between two kinds of content, and each page should keep them clearly separated into distinct sections: + +- **Evergreen guides** (most pages, e.g. `copilot-configuration-basics.md`, `building-custom-agents.md`, `installing-and-using-plugins.md`, `understanding-mcp-servers.md`, `automating-with-hooks.md`) must describe **current behavior as the primary voice** — write "Use X to do Y", not "In vA.B.C, X was added". These pages are not a changelog and must not be allowed to become one. +- **Compatibility and migration notes** are where release-specific history belongs: breaking changes, renamed settings, removed commands, and minimum-version requirements that a reader upgrading from an older version needs. Put this material in a `## Compatibility and Migration Notes` section at the bottom of the relevant page (create the section if it doesn't exist yet) instead of inline in the main teaching flow. + +Prefer **consolidation over addition**: + +- Before adding a new inline `(vX.Y.Z+)` note, check whether the same section already has one or more older version notes on the same setting, command, or field. If so, rewrite that passage to describe only the current behavior, and move any genuinely useful migration detail (old name, old default, what breaks) into the Compatibility and Migration Notes section. +- Do not add a new inline version tag for a feature that has been generally available for more than a couple of releases — just document it as the current behavior. +- Only keep an inline version tag when a reader must know the version to make a decision right now (e.g., "requires v1.0.80 or later"). +- If a page's main teaching flow already has more than roughly 8–10 inline version tags outside of a Compatibility and Migration Notes section, treat that as a signal to do a consolidation pass on that page during this run, not just append another note. + ### For new pages: A new page should be created for major features or capabilities that warrant their own documentation (e.g., a new feature of Copilot, a new pattern for working with Copilot, etc.). @@ -77,7 +90,7 @@ To create a new page: ### For updates to existing pages: -If the new information can be added to existing pages, edit those pages to include refinements, new sections, or updated information as needed. Make sure to update any relevant links in the "Further Reading" sections. +If the new information can be added to existing pages, edit those pages to include refinements, new sections, or updated information as needed, following the content model above. Make sure to update any relevant links in the "Further Reading" sections. ## Step 4 — Open a pull request @@ -86,5 +99,6 @@ Create a pull request with your changes, using the `main` branch as the base bra 1. What new features or changes were found 2. What sections of the guide were updated 3. Links to the source announcements +4. **Content cleanup** — what older inline version notes were consolidated, rewritten as current behavior, or moved into a Compatibility and Migration Notes section, or a brief note that none needed changes this run The PR should target the `main` branch and include the labels `automated-update` and `copilot-updates`. diff --git a/website/src/content/docs/learning-hub/automating-with-hooks.md b/website/src/content/docs/learning-hub/automating-with-hooks.md index b3e16856..6765696c 100644 --- a/website/src/content/docs/learning-hub/automating-with-hooks.md +++ b/website/src/content/docs/learning-hub/automating-with-hooks.md @@ -3,7 +3,7 @@ title: 'Automating with Hooks' description: 'Learn how to use hooks to automate lifecycle events like formatting, linting, and governance checks during Copilot agent sessions.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-08-28 +lastUpdated: 2026-09-22 estimatedReadingTime: '8 minutes' tags: - hooks @@ -89,7 +89,7 @@ Hooks can trigger on several lifecycle events: |-------|---------------|------------------| | `sessionStart` | Agent session begins or resumes | Initialize environments, log session starts, validate project state | | `sessionEnd` | Agent session completes or is terminated | Clean up temp files, generate reports, send notifications | -| `userPromptSubmitted` | User submits a prompt | Log requests for auditing and compliance; handle requests directly without invoking the LLM (v1.0.44+); inject `additionalContext` into the model prompt (v1.0.65+) | +| `userPromptSubmitted` | User submits a prompt | Log requests for auditing and compliance; handle requests directly without invoking the LLM; inject `additionalContext` into the model prompt | | `preToolUse` | Before the agent uses any tool (e.g., `bash`, `edit`) | **Approve or deny** tool executions, block dangerous commands, enforce security policies | | `postToolUse` | After a tool **successfully** completes execution | Log results, track usage, format code after edits | | `postToolUseFailure` | When a tool call **fails with an error** | Log errors for debugging, send failure alerts, track error patterns | @@ -118,7 +118,7 @@ cat < **Important (v1.0.36+)**: Prior to v1.0.36, the `matcher` field was silently ignored — hooks with a `matcher` fired for all tool calls regardless of the regex. After upgrading to v1.0.36 or later, only tool calls whose name fully matches the `matcher` regex will trigger the hook. Review any existing `preToolUse`/`postToolUse` hooks that use `matcher` to ensure they still fire as expected. - -> **Fix (v1.0.63+)**: A bug caused `postToolUse` matchers using pipe-separated patterns (e.g., `"matcher": "Edit|Write"`) to be silently dropped, so hooks targeting multiple tools were incorrectly firing for all tool calls. This is fixed in v1.0.63 — `postToolUse` matchers now work correctly. If you rely on a formatter or linter that runs after specific tools, upgrade to v1.0.63 or later to ensure it fires only when intended. +**matcher** *(optional)*: A regular expression matched against the tool name. When present, the hook only fires for tools whose name fully matches the regex. For example, `"^bash$"` ensures the hook only runs for the `bash` tool, not for `edit` or other tools. This is particularly useful for `preToolUse` and `postToolUse` hooks where you want to target a specific tool. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) for historical matcher bug fixes if a hook using `matcher` doesn't seem to fire as expected on an older CLI version. **cwd**: Working directory for the command (relative to repository root). @@ -214,7 +210,7 @@ Hooks support two types: `"command"` for running local shell scripts, and `"http **env**: Additional environment variables merged with the existing environment. -> **New (v1.0.81+)**: Hooks can now receive the current OpenTelemetry trace context so they can emit correlated spans. Hook inputs gain a `traceparent` field (plus `tracestate` when the span carries vendor-specific state); command hooks also receive these as environment variables, making it possible to link hook telemetry with the rest of a session's trace. +Hooks receive the current OpenTelemetry trace context so they can emit correlated spans. Hook inputs gain a `traceparent` field (plus `tracestate` when the span carries vendor-specific state); command hooks also receive these as environment variables, making it possible to link hook telemetry with the rest of a session's trace. #### HTTP hooks (`type: "http"`) @@ -265,7 +261,7 @@ automatically before the agent commits changes. The `PermissionRequest` hook fires when the CLI shows a permission prompt to the user — for example, when the agent wants to run a shell command for the first time. Unlike `preToolUse` (which can block specific tool *calls*), `PermissionRequest` intercepts the permission approval UI itself, making it ideal for **headless and CI environments** where no one is available to click "Allow". -> **Location-based persistence (v1.0.37+)**: Permission approvals are now persisted by directory by default — once you approve a permission for a given working directory, that approval carries over to future sessions started in the same directory. You no longer need to re-approve the same tools every time. Use `PermissionRequest` hooks to automate approvals in CI, and rely on the persisted approvals for interactive local sessions. +Permission approvals are persisted by directory by default — once you approve a permission for a given working directory, that approval carries over to future sessions started in the same directory. You no longer need to re-approve the same tools every time. Use `PermissionRequest` hooks to automate approvals in CI, and rely on the persisted approvals for interactive local sessions. When your hook script exits with code `0`, the permission request is **approved**. Exit with a non-zero code to **deny** it (the user will still see the prompt). @@ -299,11 +295,11 @@ exit 1 # deny (let the user decide interactively) > **Security note**: Use `PermissionRequest` hooks carefully. Blanket auto-approval in non-CI environments removes an important safety check. Scope the auto-approval logic precisely (e.g., only in CI, only for specific tools). -> **Prompt mode security (v1.0.40+)**: When running the CLI in **prompt mode** (`copilot -p "..."`) — the non-interactive mode commonly used in CI pipelines — repo hooks are **disabled by default** for security. To opt in to repo hooks in prompt mode, set the environment variable `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=true` before running the command: +When running the CLI in **prompt mode** (`copilot -p "..."`) — the non-interactive mode commonly used in CI pipelines — repo hooks are **disabled by default** for security. To opt in to repo hooks in prompt mode, set the environment variable `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=true` before running the command: > ```bash > GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=true copilot -p "..." --no-ask-user > ``` -> This is a secure-by-default change: it prevents untrusted repository hooks from firing silently when a user runs a quick prompt command in an unfamiliar repository. Similarly, workspace MCP servers are disabled in prompt mode by default; opt in with `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true`. Extensions follow a mixed model (v1.0.41+): **user-level extensions** (from `~/.copilot/`) load automatically in prompt mode, but **project-level extensions and management tools** are disabled by default — opt in with `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true` to load them. +> This is a secure-by-default behavior: it prevents untrusted repository hooks from firing silently when a user runs a quick prompt command in an unfamiliar repository. Similarly, workspace MCP servers are disabled in prompt mode by default; opt in with `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true`. Extensions follow a mixed model: **user-level extensions** (from `~/.copilot/`) load automatically in prompt mode, but **project-level extensions and management tools** are disabled by default — opt in with `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true` to load them. ### Handling Tool Failures with postToolUseFailure @@ -325,9 +321,7 @@ The `postToolUseFailure` hook fires when a tool call fails with an error — dis } ``` -The hook receives JSON input describing which tool failed and the error message. This separation lets you write targeted failure-handling logic without adding conditional checks to your `postToolUse` hooks. - -> **Note**: Before v1.0.15, `postToolUse` fired for both successful and failed tool calls. If you have existing `postToolUse` hooks that handle failures, migrate that logic to `postToolUseFailure`. +The hook receives JSON input describing which tool failed and the error message. This separation lets you write targeted failure-handling logic without adding conditional checks to your `postToolUse` hooks. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you have older `postToolUse` hooks that also handle failures. ### Auto-Format After Edits @@ -394,7 +388,7 @@ Block dangerous commands before they execute. Use the `matcher` field to target The `preToolUse` hook receives JSON input with details about the tool being called. Your script can inspect this input and exit with a non-zero code to **deny** the tool execution, or exit with zero to **approve** it. -> **Exit code 2 — silent deny (v1.0.69+)**: A `preToolUse` hook that exits with code `2` **denies the tool call silently** — the agent receives a denial without any error message being surfaced to the user. This is useful when you want to block a tool call as a policy decision without triggering a noisy failure (for example, blocking network access in CI without alarming users). Exit with any other non-zero code (e.g., `1`) to deny and show an error message. +> **Exit code 2 — silent deny**: A `preToolUse` hook that exits with code `2` **denies the tool call silently** — the agent receives a denial without any error message being surfaced to the user. This is useful when you want to block a tool call as a policy decision without triggering a noisy failure (for example, blocking network access in CI without alarming users). Exit with any other non-zero code (e.g., `1`) to deny and show an error message. ### Modifying Tool Arguments with preToolUse @@ -469,9 +463,9 @@ Scan user prompts for potential security threats and log session activity: This pattern is useful for enterprise environments that need to audit AI interactions for compliance. -### Handling Requests Directly with userPromptSubmitted (v1.0.44+) +### Handling Requests Directly with userPromptSubmitted -Since v1.0.44, `userPromptSubmitted` hooks can do more than log or block — they can **handle a request entirely**, returning a response to the user without making any model call. When your hook script writes a JSON object with a `response` field to stdout, the CLI delivers that text to the user and skips the LLM altogether. +`userPromptSubmitted` hooks can do more than log or block — they can **handle a request entirely**, returning a response to the user without making any model call. When your hook script writes a JSON object with a `response` field to stdout, the CLI delivers that text to the user and skips the LLM altogether. This is useful for: - **FAQ bots**: Return canned answers for common questions without spending model quota @@ -652,6 +646,13 @@ echo "Pre-commit checks passed ✅" - **Test locally first**: Run hook scripts manually before relying on them in agent sessions. - **Layer hooks, don't overload**: Use multiple hook entries for independent checks rather than one monolithic script. +## Compatibility and Migration Notes + +This section collects behavior changes from past releases that may explain historical bugs or inconsistent-looking output — everything above describes current behavior. + +- **The `matcher` field bug fixes**: Before **v1.0.36**, `matcher` was silently ignored entirely, so hooks fired for all tool calls regardless of the regex. In **v1.0.63**, a follow-up bug affecting `postToolUse` matchers with pipe-separated patterns (e.g., `"matcher": "Edit|Write"`) was fixed; before that release, those matchers were silently dropped. If a hook using `matcher` doesn't fire selectively as expected, check the CLI version before troubleshooting the hook configuration. +- **`postToolUse` used to also fire on tool failures.** Before **v1.0.15**, it fired for both successful and failed tool calls. It now only fires on success; failures are reported to the dedicated `postToolUseFailure` event. Migrate any failure-handling logic in a `postToolUse` hook to `postToolUseFailure`. + ## Common Questions **Q: Where do I put hooks configuration files?** @@ -667,7 +668,7 @@ For team-wide hooks that everyone should use, `.github/hooks/` is the recommende **Q: Can hooks access the user's prompt text?** -A: Yes. For `userPromptSubmitted` events the prompt content is available via JSON input to the hook script. Since v1.0.44, these hooks can also **respond directly** by writing `{"response": "..."}` to stdout — the CLI delivers that text to the user and skips the LLM entirely. Other hooks like `preToolUse` and `postToolUse` receive context about the tool being called. See the [GitHub Copilot hooks documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-hooks) for details. +A: Yes. For `userPromptSubmitted` events the prompt content is available via JSON input to the hook script. These hooks can also **respond directly** by writing `{"response": "..."}` to stdout — the CLI delivers that text to the user and skips the LLM entirely. Other hooks like `preToolUse` and `postToolUse` receive context about the tool being called. See the [GitHub Copilot hooks documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-hooks) for details. **Q: What happens if a hook times out?** diff --git a/website/src/content/docs/learning-hub/building-custom-agents.md b/website/src/content/docs/learning-hub/building-custom-agents.md index 3ad3e7cb..0cf56a3d 100644 --- a/website/src/content/docs/learning-hub/building-custom-agents.md +++ b/website/src/content/docs/learning-hub/building-custom-agents.md @@ -3,7 +3,7 @@ title: 'Building Custom Agents' description: 'Learn how to create specialized GitHub Copilot agents with custom personas, tool integrations, and domain expertise.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-09-05 +lastUpdated: 2026-09-22 estimatedReadingTime: '10 minutes' tags: - agents @@ -73,7 +73,7 @@ tools: ['codebase', 'terminal', 'github'] **model** (recommended): The AI model that powers the agent. Choose based on the complexity of the task—use more capable models for nuanced reasoning. -> **Model fallback lists (v1.0.83+)**: `model` can list several models, tried in order until one is available to you — useful if your preferred model is temporarily rate-limited or not enrolled for your account. Pair it with `model-policy: required` to keep the agent restricted to that list even if the user tries to switch models mid-session: +**Model fallback lists**: `model` can list several models, tried in order until one is available to you — useful if your preferred model is temporarily rate-limited or not enrolled for your account. Pair it with `model-policy: required` to keep the agent restricted to that list even if the user tries to switch models mid-session: > > ```yaml > --- @@ -84,7 +84,7 @@ tools: ['codebase', 'terminal', 'github'] > --- > ``` -**reasoningEffort** *(v1.0.66+)*: Override the reasoning effort level for this agent. Accepted values are `low`, `medium`, and `high`. This lets you pin specific agents to a cost/quality tradeoff regardless of the user's global setting — for example, a quick code-formatting agent can use `low` effort, while a security reviewer uses `high`: +**reasoningEffort**: Override the reasoning effort level for this agent. Accepted values are `low`, `medium`, and `high`. This lets you pin specific agents to a cost/quality tradeoff regardless of the user's global setting — for example, a quick code-formatting agent can use `low` effort, while a security reviewer uses `high`: ```yaml --- @@ -209,7 +209,7 @@ You are a release manager who automates the release process. Create agents that enforce standards: -> **Built-in `/security-review`**: Before creating a custom security-reviewer agent, note that GitHub Copilot CLI includes a built-in `/security-review` command (available to all users since v1.0.64). It performs a security-focused analysis of staged changes or specified files. Custom security-reviewer agents are still valuable for domain-specific rules, team conventions, and deep integration with MCP tools like Sentry or SAST platforms. +> **Built-in `/security-review`**: Before creating a custom security-reviewer agent, note that GitHub Copilot CLI includes a built-in `/security-review` command available to all users. It performs a security-focused analysis of staged changes or specified files. Custom security-reviewer agents are still valuable for domain-specific rules, team conventions, and deep integration with MCP tools like Sentry or SAST platforms. ```markdown --- @@ -265,11 +265,11 @@ The agent can then query your database, analyze query plans, and suggest optimiz | Scenario | Recommended Model | |----------|-------------------| -| Most demanding reasoning, security review | Claude Sonnet 5 *(v1.0.67+)* | +| Most demanding reasoning, security review | Claude Sonnet 5 | | Complex reasoning, analysis | Claude Sonnet 4 | -| Code generation, tool-driven agentic work | GPT-5.6 *(v1.0.70+)* | +| Code generation, tool-driven agentic work | GPT-5.6 | | Code generation, refactoring | GPT-4.1 | -| Code-specialized tasks, large context | kimi-k2.7-code *(v1.0.68+)*, kimi-k3 *(v1.0.79+)* | +| Code-specialized tasks, large context | kimi-k2.7-code, kimi-k3 | | Quick analysis, simple tasks | Claude Haiku or GPT-4.1-mini | | Large codebase understanding | Models with larger context windows | @@ -292,7 +292,7 @@ Keep agents focused—one persona per file. If you find an agent trying to do to A: In VS Code, open Copilot Chat and use the agent picker dropdown at the top of the chat panel. Your custom agents appear alongside built-in options. You can also `@mention` an agent by name. -In Copilot CLI, custom agents are discoverable via the agent picker inside a session. Clients that integrate with Copilot CLI using the **Agent Coordination Protocol (ACP)** can also list available custom agents and switch between them programmatically via the `agent` session configuration option (v1.0.40+). This allows tools like Zed, Neovim plugins, and CI pipelines driving Copilot via ACP to surface the agent picker and switch agents without requiring a slash command. ACP clients also receive the agent's **live plan** as it works through multi-step tasks (v1.0.40+), so they can display real-time progress to their users without waiting for each turn to complete. +In Copilot CLI, custom agents are discoverable via the agent picker inside a session. Clients that integrate with Copilot CLI using the **Agent Coordination Protocol (ACP)** can also list available custom agents and switch between them programmatically via the `agent` session configuration option. This allows tools like Zed, Neovim plugins, and CI pipelines driving Copilot via ACP to surface the agent picker and switch agents without requiring a slash command. ACP clients also receive the agent's **live plan** as it works through multi-step tasks, so they can display real-time progress to their users without waiting for each turn to complete. **Q: Can agents use skills?** diff --git a/website/src/content/docs/learning-hub/copilot-configuration-basics.md b/website/src/content/docs/learning-hub/copilot-configuration-basics.md index b0f47e64..c9e4665d 100644 --- a/website/src/content/docs/learning-hub/copilot-configuration-basics.md +++ b/website/src/content/docs/learning-hub/copilot-configuration-basics.md @@ -3,7 +3,7 @@ title: 'Copilot Configuration Basics' description: 'Learn how to configure GitHub Copilot at user, workspace, and repository levels to optimize your AI-assisted development experience.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-09-12 +lastUpdated: 2026-09-22 estimatedReadingTime: '10 minutes' tags: - configuration @@ -209,7 +209,7 @@ The `~/.agents/skills/` path aligns with the VS Code GitHub Copilot for Azure ex ### Pinning Model and Effort via `.github/copilot/settings.json` -*(v1.0.70+)* A **trusted repository** can pin the model, reasoning effort level, and context tier for all sessions working in that repository by adding a `.github/copilot/settings.json` file. This is a team governance feature that ensures everyone uses a consistent model configuration without relying on individual user settings: +A **trusted repository** can pin the model, reasoning effort level, and context tier for all sessions working in that repository by adding a `.github/copilot/settings.json` file. This is a team governance feature that ensures everyone uses a consistent model configuration without relying on individual user settings: ```json { @@ -274,7 +274,7 @@ See [references/test-patterns.md](references/test-patterns.md) for standard patt Skills can also bundle reference files, templates, and scripts in their folder, giving the AI richer context than a single file can provide. Unlike the older prompt format, skills can be discovered and invoked by agents automatically. -**Dynamic skill retrieval** (v1.0.66+): By default, Copilot CLI uses embeddings-based retrieval to automatically surface the most relevant skills for each prompt. You can toggle this behavior with the `--dynamic-retrieval` flag or the `dynamicRetrieval` config setting. To disable embeddings-based retrieval (for example, to force all configured skills to always be loaded): +**Dynamic skill retrieval**: By default, Copilot CLI uses embeddings-based retrieval to automatically surface the most relevant skills for each prompt. You can toggle this behavior with the `--dynamic-retrieval` flag or the `dynamicRetrieval` config setting. To disable embeddings-based retrieval (for example, to force all configured skills to always be loaded): ```bash copilot --dynamic-retrieval skills=off @@ -426,17 +426,17 @@ CLI settings use **camelCase** naming. Key settings added in recent releases: | `include_gitignored` | Include gitignored files in `@` file search | | `extension_mode` | Control extensibility (agent tools and plugins) | | `continueOnAutoMode` | Automatically switch to the auto model on rate limit instead of pausing | -| `proxy` | HTTP(S) proxy URL for all outbound CLI requests (e.g., `http://proxy.example.com:8080`) (v1.0.64+) | -| `sessionLimits` | Restrict credit or turn usage for a session; limits apply across the current conversation and reset on `/clear` (v1.0.66+) | -| `stayInAutopilot` | Keep the CLI in autopilot mode after an autopilot task completes, instead of returning to interactive mode (v1.0.69+) | -| `defaultMode` | Startup mode for new interactive sessions (e.g., `interactive`, `autopilot`, `plan`) (v1.0.81+) | -| `defaultPermissionMode` | Default approval behaviour for new interactive sessions, independent from `defaultMode` (v1.0.81+) | +| `proxy` | HTTP(S) proxy URL for all outbound CLI requests (e.g., `http://proxy.example.com:8080`) | +| `sessionLimits` | Restrict credit or turn usage for a session; limits apply across the current conversation and reset on `/clear` | +| `stayInAutopilot` | Keep the CLI in autopilot mode after an autopilot task completes, instead of returning to interactive mode | +| `defaultMode` | Startup mode for new interactive sessions (e.g., `interactive`, `autopilot`, `plan`) | +| `defaultPermissionMode` | Default approval behaviour for new interactive sessions, independent from `defaultMode` | > **Note**: Older snake_case names (e.g., `include_gitignored`, `auto_updates_channel`) are still accepted for backward compatibility, but camelCase is now the preferred format. -> **Session restore after a crash (v1.0.81+)**: If the CLI is interrupted unexpectedly — a crash or a machine restart — startup now offers to restore any sessions that were still open, so you don't have to reopen each terminal by hand. +If the CLI is interrupted unexpectedly — a crash or a machine restart — startup offers to restore any sessions that were still open, so you don't have to reopen each terminal by hand. -> **Piping an auth token (v1.0.81+)**: Use `copilot login --with-token` to read an authentication token from stdin instead of going through the interactive browser or device-code flow — useful for scripted or containerized setups where a token is already available in the environment. +Use `copilot login --with-token` to read an authentication token from stdin instead of going through the interactive browser or device-code flow — useful for scripted or containerized setups where a token is already available in the environment. In addition to the main config file, GitHub Copilot CLI reads two optional per-project files for repository-specific overrides: @@ -445,23 +445,21 @@ In addition to the main config file, GitHub Copilot CLI reads two optional per-p These files follow the same format as `config.json` and are loaded after the global config, so they can tailor CLI behaviour—including hook definitions—per repository without touching `.github/`. -> **Important (v1.0.36+)**: Custom agents, skills, and commands placed in `~/.claude/` (the Claude Code user directory) are **no longer loaded** by GitHub Copilot CLI. Only `~/.claude/settings.json` is read for configuration. If you previously stored personal agents or skills in `~/.claude/`, move them to the supported locations: `~/.copilot/agents/` for user-level agents, `~/.copilot/skills/` or `~/.agents/skills/` for personal skills, or `.github/agents/` and `.github/skills/` in your repositories for project-level customizations. +> **Note**: Custom agents, skills, and commands placed in `~/.claude/` (the Claude Code user directory) are **not** loaded by GitHub Copilot CLI. Only `~/.claude/settings.json` is read for configuration. Store personal agents and skills in the supported locations instead: `~/.copilot/agents/` for user-level agents, `~/.copilot/skills/` or `~/.agents/skills/` for personal skills, or `.github/agents/` and `.github/skills/` in your repositories for project-level customizations. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you previously relied on `~/.claude/` being loaded. ### Model Picker -The model picker opens in a **full-screen view** with inline reasoning effort adjustment. Use the **← / →** arrow keys to change the reasoning effort level (`low`, `medium`, `high`) directly from the picker without leaving the session. The current reasoning effort level is also displayed in the model header (e.g., `claude-sonnet-4.6 (high)`) so you always know which level is active. +The model picker opens in a **full-screen view** with inline reasoning effort adjustment. Use the **← / →** arrow keys to change the reasoning effort level (`low`, `medium`, `high`) directly from the picker without leaving the session. The current reasoning effort level is also displayed in the model header (e.g., `claude-sonnet-4.6 (high)`) so you always know which level is active. Models are grouped into **Recent**, **Recommended**, **New**, and other sections instead of a single flat list, making it faster to find the model you want — press **Shift+Tab** to switch between grouping views. -**Grouped model picker** *(v1.0.79+)*: The model picker now groups models into **Recent**, **Recommended**, **New**, and other sections instead of a single flat list, making it faster to find the model you want. Press **Shift+Tab** to switch between grouping views. +`/model` changes the model for the **current session only** by default. Use `/config model` to set the default model for future sessions. -**Session-scoped model selection** *(v1.0.79+)*: `/model` now changes the model for the **current session only** by default. Use `/config model` to set the default model for future sessions — previously `/model` changed both at once, which made it easy to accidentally change your global default while just trying something out in one session. +**Auto mode and server-side model routing**: When you select **Auto** as your model, the CLI uses server-side model routing for real-time model selection. Instead of locking in a single model at session start, Auto mode evaluates each request and routes it to the most appropriate model dynamically. This means straightforward questions can be handled by a faster model while complex reasoning tasks are automatically escalated — without you needing to switch models manually. -**Auto mode and server-side model routing** (v1.0.43+): When you select **Auto** as your model, the CLI uses server-side model routing for real-time model selection. Instead of locking in a single model at session start, Auto mode evaluates each request and routes it to the most appropriate model dynamically. This means straightforward questions can be handled by a faster model while complex reasoning tasks are automatically escalated — without you needing to switch models manually. +**Model family aliases**: Instead of typing a full model name, you can use short family aliases in the model setting: `opus`, `sonnet`, `haiku` (Anthropic), and `gpt`, `gemini` (Google/OpenAI). The CLI resolves the alias to the latest available model in that family. This is especially useful in scripts or configuration files where you want to track the best model in a family without hardcoding a version string. Current models include **Claude Opus 5** and **Claude Fable 5.1** (Anthropic), **Grok 4.5** and **Grok 4.6** (xAI, with `xhigh` reasoning effort support), **Gemini 3.7 Flash** (Google), and **GPT-6 Astra** (OpenAI). The model picker also periodically retires older models no longer worth recommending, so don't be surprised if a model you previously pinned disappears from the list — check [Compatibility and Migration Notes](#compatibility-and-migration-notes) if that happens. -**Model family aliases** (v1.0.64+): Instead of typing a full model name, you can use short family aliases in the model setting: `opus`, `sonnet`, `haiku` (Anthropic), and `gpt`, `gemini` (Google/OpenAI). The CLI resolves the alias to the latest available model in that family. This is especially useful in scripts or configuration files where you want to track the best model in a family without hardcoding a version string. Recent models available include **Claude Opus 5** (v1.0.75+), the latest in Anthropic's Opus family for the most demanding tasks, **Grok 4.5** (v1.0.76+) from xAI, **Gemini 3.7 Flash** (v1.0.81+), **Claude Fable 5.1** (v1.0.83+), and **GPT-6 Astra** (v1.0.84+). **Grok 4.6** (v1.0.81+) also gains support for the `xhigh` reasoning effort level, one step above `high`, for the most demanding reasoning tasks. The `/model picker` also periodically retires older models no longer worth recommending — a recent cleanup removed several deprecated Claude and Gemini entries (v1.0.83+), so don't be surprised if a model you previously pinned disappears from the list. +**Model fallback lists**: Custom agents can set `model` to a list of several models instead of a single name. Copilot tries each one in order until it finds one available to your account — useful when your preferred model is temporarily rate-limited or not enrolled. Pair this with `model-policy: required` to keep the agent restricted to that list even if you try to switch models mid-session. See [Building Custom Agents](../building-custom-agents/) for the frontmatter syntax. -**Model fallback lists** *(v1.0.83+)*: Custom agents can set `model` to a list of several models instead of a single name. Copilot tries each one in order until it finds one available to your account — useful when your preferred model is temporarily rate-limited or not enrolled. Pair this with `model-policy: required` to keep the agent restricted to that list even if you try to switch models mid-session. See [Building Custom Agents](../building-custom-agents/) for the frontmatter syntax. - -**Plan mode model** *(v1.0.74+)*: When using plan mode (which blocks file mutations and keeps changes in a planning phase), you can assign a *separate* model specifically for planning — different from your regular session model. This lets you use a fast, cost-effective model for plan drafting while keeping a more capable model on standby for the implementation phase: +**Plan mode model**: When using plan mode (which blocks file mutations and keeps changes in a planning phase), you can assign a *separate* model specifically for planning — different from your regular session model. This lets you use a fast, cost-effective model for plan drafting while keeping a more capable model on standby for the implementation phase: ``` /model plan # open the picker to choose a model for plan mode @@ -473,7 +471,7 @@ When you leave plan mode, the CLI automatically reverts to your session model. T ### CLI Session Commands -The `/settings` command (v1.0.61+) opens an interactive dialog to browse and edit all user settings in one place. Use it to discover available settings, toggle options, and update values without manually editing your config file: +The `/settings` command opens an interactive dialog to browse and edit all user settings in one place. Use it to discover available settings, toggle options, and update values without manually editing your config file: ``` /settings @@ -481,7 +479,7 @@ The `/settings` command (v1.0.61+) opens an interactive dialog to browse and edi The settings dialog supports search — type to filter settings by name. Changes take effect immediately. -*(v1.0.70+)* The `/settings` command and the `/model` command both support **`--repo` and `--local` flags** for explicitly scoping which layer of settings you want to view or edit: +The `/settings` command and the `/model` command both support **`--repo` and `--local` flags** for explicitly scoping which layer of settings you want to view or edit: ``` /settings --repo # view/edit repository-scoped settings @@ -490,7 +488,7 @@ The settings dialog supports search — type to filter settings by name. Changes /model --local # view/edit your personal model preference ``` -These flags mirror the **Repo** and **Repo (local)** scope tabs available in the `/settings` dashboard (v1.0.71+), making it easier to manage per-repository vs. user-global configuration without ambiguity. In v1.0.71+, the `/settings` dashboard also shows **Repo** and **Repo (local)** tabs alongside the existing user-level view, giving you a unified place to see which settings are applied at each layer. +These flags mirror the **Repo** and **Repo (local)** scope tabs available in the `/settings` dashboard, giving you a unified place to see which settings are applied at each layer without ambiguity. GitHub Copilot CLI has two commands for managing session state, with distinct behaviours: @@ -529,7 +527,7 @@ You can also press **x** on a highlighted session in the session picker (`--resu In the session picker, press **`s`** to cycle the sort order: relevance, last used, created, or name. The picker also shows the branch name and idle/in-use status for each session. -**Sessions Sidebar and Tab** *(v1.0.76+)*: The Sessions Sidebar is a persistent panel for managing multiple concurrent sessions — switch between them, spawn new ones, and see their status at a glance, all without leaving your current session. As of v1.0.79, the Sessions Sidebar has graduated from experimental and is available by default alongside a dedicated **Sessions tab**. Enable or customize it in `/settings`: +**Sessions Sidebar and Tab**: The Sessions Sidebar is a persistent panel for managing multiple concurrent sessions — switch between them, spawn new ones, and see their status at a glance, all without leaving your current session. It is available by default alongside a dedicated **Sessions tab**. Enable or customize it in `/settings`: ``` /settings sidebar @@ -537,9 +535,9 @@ In the session picker, press **`s`** to cycle the sort order: relevance, last us With the sidebar open, you can see all running and backgrounded sessions in a split-view panel alongside your active conversation. Sessions are listed with their name, working directory, and running status. Click or keyboard-navigate (arrow keys, **n** to spawn, **x** twice to close) to switch sessions instantly. Use this when you regularly juggle several parallel workstreams and want a persistent view of all your sessions rather than accessing them through the `/resume` picker. -**Sidebar sort order** *(v1.0.83+)*: The split Sessions sidebar supports **Recent**, **Created**, **Name**, and classic **None** sorting so you can order the list the way that fits your workflow. Your chosen order is remembered across CLI restarts. +**Sidebar sort order**: The split Sessions sidebar supports **Recent**, **Created**, **Name**, and classic **None** sorting so you can order the list the way that fits your workflow. Your chosen order is remembered across CLI restarts. -**Windows 11 taskbar status** *(v1.0.83+)*: On Windows 11, running Copilot CLI sessions now appear in the taskbar with live hover status cards, so you can check on a background session's progress without switching back to its terminal window. +**Windows 11 taskbar status**: On Windows 11, running Copilot CLI sessions appear in the taskbar with live hover status cards, so you can check on a background session's progress without switching back to its terminal window. The `/rewind` command opens a timeline picker that lets you roll back the conversation to any earlier point in history. You can also trigger it by pressing **double-Esc**: @@ -547,7 +545,7 @@ The `/rewind` command opens a timeline picker that lets you roll back the conver /rewind ``` -When you select a point to roll back to, `/rewind` presents a choice: roll back the **conversation only** (leaving your files as-is) or roll back **both the conversation and file changes** (restoring files to the state they were in at that point). Since v1.0.78, `/rewind` no longer requires git — it restores only the files Copilot changed, skipping any file whose contents no longer match what Copilot last wrote. +When you select a point to roll back to, `/rewind` presents a choice: roll back the **conversation only** (leaving your files as-is) or roll back **both the conversation and file changes** (restoring files to the state they were in at that point). `/rewind` does not require git — it restores only the files Copilot changed, skipping any file whose contents no longer match what Copilot last wrote. Use `/rewind` when you want to branch off from a different point in the conversation, rather than just undoing the most recent turn. @@ -559,17 +557,17 @@ The `/undo` command reverts the last turn—including any file changes the agent Use `/undo` when the agent's last response went in an unwanted direction and you want to try a different approach from that point. -The `/fork` command (v1.0.45+) copies the current session into a **new independent session** that starts from the same conversation state. The original session continues unchanged — you can switch back to it at any time. This is useful when you want to explore two different approaches to a problem simultaneously. In v1.0.64+, `/branch` is available as an alias for `/fork` (matching Claude Code's command naming): +The `/fork` command copies the current session into a **new independent session** that starts from the same conversation state. The original session continues unchanged — you can switch back to it at any time. This is useful when you want to explore two different approaches to a problem simultaneously. `/branch` is available as an alias for `/fork` (matching Claude Code's command naming): ``` /fork # fork with an auto-generated name -/fork "my-experiment" # fork with a custom name (v1.0.47+) -/branch # alias for /fork (v1.0.64+) +/fork "my-experiment" # fork with a custom name +/branch # alias for /fork ``` -After forking, the new session is immediately active. Both sessions share the same history up to the fork point but accumulate changes independently from that moment forward. Use `/fork` to experiment with a risky refactor without abandoning your current working session. Since v1.0.47, forked sessions display their **origin session** name in the sessions dialog, making it easy to trace which session a fork came from. +After forking, the new session is immediately active. Both sessions share the same history up to the fork point but accumulate changes independently from that moment forward. Use `/fork` to experiment with a risky refactor without abandoning your current working session. Forked sessions display their **origin session** name in the sessions dialog, making it easy to trace which session a fork came from. -The `/cd` command changes the working directory for the current session. Since v1.0.65, the working directory **persists when you resume a session** — if you restart the CLI and resume, you return to the same directory automatically. Changing directory also triggers discovery of custom agents in the new location, so switching to a different project loads its agents without a restart: +The `/cd` command changes the working directory for the current session. The working directory **persists when you resume a session** — if you restart the CLI and resume, you return to the same directory automatically. Changing directory also triggers discovery of custom agents in the new location, so switching to a different project loads its agents without a restart: ``` /cd ~/projects/my-other-repo @@ -577,13 +575,13 @@ The `/cd` command changes the working directory for the current session. Since v This is useful when you have multiple backgrounded sessions each focused on a different project directory. -The `/worktree` command (v1.0.61+, also aliased `/move`) creates a new git worktree and switches into it, moving any uncommitted changes along. This lets you start working on a parallel branch without leaving your current terminal session: +The `/worktree` command (also aliased `/move`) creates a new git worktree and switches into it, moving any uncommitted changes along. This lets you start working on a parallel branch without leaving your current terminal session: ``` /worktree my-feature-branch ``` -In v1.0.66+, you can pass a task description to `/worktree` to name the branch from the task and immediately run the task as the first prompt in the new worktree — all in one step: +You can also pass a task description to `/worktree` to name the branch from the task and immediately run the task as the first prompt in the new worktree — all in one step: ``` /worktree fix the login redirect @@ -591,21 +589,21 @@ In v1.0.66+, you can pass a task description to `/worktree` to name the branch f This creates a branch named from your task description and begins working on it immediately, making it easy to spin up parallel work without stopping to think of a branch name. -After the command runs, the session is inside the new worktree. Use this when you want to work on a second task in parallel without stashing changes or opening a new terminal. In v1.0.64+ you can also use the experimental `--worktree` flag at startup (`copilot -w [name]`) to create or reuse a worktree under `.worktrees/` before the session begins. +After the command runs, the session is inside the new worktree. Use this when you want to work on a second task in parallel without stashing changes or opening a new terminal. You can also use the experimental `--worktree` flag at startup (`copilot -w [name]`) to create or reuse a worktree under `.worktrees/` before the session begins. -The `/new-worktree` command *(v1.0.78+, experimental)* creates a new worktree and starts a **fresh conversation** in it — without inheriting the current session's history. This is useful when you want a completely clean slate for a new task in a parallel branch: +The `/new-worktree` command *(experimental)* creates a new worktree and starts a **fresh conversation** in it — without inheriting the current session's history. This is useful when you want a completely clean slate for a new task in a parallel branch: ``` /new-worktree my-feature-branch ``` -Unlike `/worktree` (which keeps the current conversation), `/new-worktree` is the equivalent of opening a new terminal, switching to a worktree, and starting fresh — all in one step. In v1.0.79+, the same behaviour is also available as a subcommand shorthand: +Unlike `/worktree` (which keeps the current conversation), `/new-worktree` is the equivalent of opening a new terminal, switching to a worktree, and starting fresh — all in one step. The same behaviour is also available as a subcommand shorthand: ``` /worktree new my-feature-branch ``` -The `/every` command (also available as `/loop` since v1.0.64) schedules a recurring prompt to run automatically at a specified interval. The companion `/after` command runs a prompt once after a specified delay. Both are useful for self-paced automation — polling for results, periodically summarizing progress, or triggering other slash commands on a timer: +The `/every` command (also available as `/loop`) schedules a recurring prompt to run automatically at a specified interval. The companion `/after` command runs a prompt once after a specified delay. Both are useful for self-paced automation — polling for results, periodically summarizing progress, or triggering other slash commands on a timer: ``` /every 5m Check if there are any new test failures and summarize them @@ -620,7 +618,7 @@ The interval can be specified in seconds (`s`), minutes (`m`), or hours (`h`), a > **Note**: Scheduled prompts run in the background of the current session and use your active model. They share the session context window, so very frequent scheduling with long responses may consume context rapidly. Use `/compact` if context usage becomes a concern. -The `/pr auto` command *(v1.0.66+)* starts a self-paced automation loop that drives the current pull request to CI green. Rather than running continuously, it fixes one failing item per run and paces itself around CI checks to avoid redundant work: +The `/pr auto` command starts a self-paced automation loop that drives the current pull request to CI green. Rather than running continuously, it fixes one failing item per run and paces itself around CI checks to avoid redundant work: ``` /pr auto # start fixing the current PR until CI passes @@ -629,7 +627,7 @@ The `/pr auto` command *(v1.0.66+)* starts a self-paced automation loop that dri `/pr auto` is ideal when you have a PR with failing tests or linting errors — let it work through failures one at a time while you focus on other things. `/pr automerge` extends this further: it continues until all CI checks pass, required reviews are approved, and the PR is successfully merged. Both commands can be monitored and stopped from `/loop` or `/every`, which register the running automation as a scheduleable loop task. -The `/delegate` command creates a **delegate PR** — a pull request that the coding agent works on autonomously. By default, the delegate PR targets your current branch. Use `--base` *(v1.0.69+)* to specify a different target base branch: +The `/delegate` command creates a **delegate PR** — a pull request that the coding agent works on autonomously. By default, the delegate PR targets your current branch. Use `--base` to specify a different target base branch: ``` /delegate # create a delegate PR targeting the current branch @@ -655,7 +653,7 @@ The `/chronicle` command opens an interactive timeline of everything the agent h Chronicle tracks which files were created, modified, or deleted during the session alongside the conversation that led to those changes. Use it to review what happened before a `/rewind`, audit what the agent changed, or share a summary of session activity with teammates. -The `/chronicle skills review` subcommand *(v1.0.66+)* opens an interactive review flow for proposed draft skill changes. When the agent has suggested additions or modifications to skills during a session, you can review each draft individually and choose to accept, reject, or defer: +The `/chronicle skills review` subcommand opens an interactive review flow for proposed draft skill changes. When the agent has suggested additions or modifications to skills during a session, you can review each draft individually and choose to accept, reject, or defer: ``` /chronicle skills review @@ -663,9 +661,7 @@ The `/chronicle skills review` subcommand *(v1.0.66+)* opens an interactive revi This keeps you in control of skill evolution — the agent can propose skill improvements as it discovers reusable patterns, but nothing is applied until you explicitly approve each change. -> **Note**: Session history, file tracking, and the `/chronicle` command were previously experimental features. As of v1.0.40, they are available to all users without enabling experimental mode. - -The `/diagnose` command (v1.0.64+) analyzes the current session's logs and surfaces diagnostic information to help troubleshoot unexpected behavior, performance issues, or errors: +The `/diagnose` command analyzes the current session's logs and surfaces diagnostic information to help troubleshoot unexpected behavior, performance issues, or errors: ``` /diagnose @@ -673,19 +669,17 @@ The `/diagnose` command (v1.0.64+) analyzes the current session's logs and surfa Use `/diagnose` when a session is behaving unexpectedly — it inspects session logs and reports what it finds, making it easier to share diagnostics with support or understand what happened internally. -**Keyboard shortcuts for queuing messages**: Use **Ctrl+Q** or **Ctrl+Enter** to queue a message (send it while the agent is still working). **Ctrl+D** no longer queues messages — it now has its default terminal behavior. If you have muscle memory for Ctrl+D queuing, switch to Ctrl+Q. +**Keyboard shortcuts for queuing messages**: Use **Ctrl+Q** or **Ctrl+Enter** to queue a message (send it while the agent is still working). **Ctrl+D** has its default terminal behavior and does not queue messages — if you have muscle memory for Ctrl+D queuing, switch to Ctrl+Q. -**Directable queue manager** *(v1.0.76+)*: While the agent is working, you can manage your queued messages before they are sent. Open the queue manager to **reorder**, **edit**, **remove**, or **repeat** queued messages — even send one immediately out of turn. This is useful when you think of a better follow-up mid-run or want to reprioritize what the agent works on next. +**Directable queue manager**: While the agent is working, you can manage your queued messages before they are sent. Open the queue manager to **reorder**, **edit**, **remove**, or **repeat** queued messages — even send one immediately out of turn. This is useful when you think of a better follow-up mid-run or want to reprioritize what the agent works on next. **Background running tasks**: Press **Ctrl+X → B** to move the current running task or shell command to the background. The task continues executing while you can type a new message or review earlier output. This is useful for long-running commands where you want to interact with the agent while waiting for the result. -**Shell command history in normal mode** (v1.0.65+): The **↑/↓** arrow keys and **Ctrl+R** reverse search now include past shell commands (commands run with `!`) while you are in normal (non-shell) input mode. Previously you had to type `!` to enter shell mode before history worked. Now you can recall and re-run a shell command without switching modes first — useful for quickly repeating a build, test, or diagnostic command from earlier in the session. +**Shell command history in normal mode**: The **↑/↓** arrow keys and **Ctrl+R** reverse search include past shell commands (commands run with `!`) while you are in normal (non-shell) input mode, so you can recall and re-run a shell command without switching into shell mode first — useful for quickly repeating a build, test, or diagnostic command from earlier in the session. -**Inline image rendering** (v1.0.64+): The CLI can display images inline in the terminal when your terminal supports it. If an MCP tool, agent, or attachment returns an image, it is rendered directly in the conversation timeline rather than shown as a file path or URL. This works in terminals with image protocol support (such as iTerm2, Kitty, Wezterm, and tmux with appropriate configuration). +**Inline image rendering**: The CLI can display images inline in the terminal when your terminal supports it. If an MCP tool, agent, or attachment returns an image, it is rendered directly in the conversation timeline rather than shown as a file path or URL. This works in terminals with image protocol support (such as iTerm2, Kitty, Wezterm, and tmux with appropriate configuration). -**Voice dictation** *(v1.0.81+)*: Press **Ctrl+Space** to toggle voice dictation on or off, letting you speak a prompt instead of typing it. - -**Worktree switch reliability (v1.0.82+)**: If you start typing a new message while `/worktree` or `/move` is preparing a worktree switch, that message is no longer dropped when the switch completes. +**Voice dictation**: Press **Ctrl+Space** to toggle voice dictation on or off, letting you speak a prompt instead of typing it. The `/ask` command lets you ask a quick question without affecting your conversation history. The current session context is preserved, so you can use it for one-off lookups without derailing an ongoing task. Responses are rendered as full markdown, including tables and formatted links: @@ -693,7 +687,7 @@ The `/ask` command lets you ask a quick question without affecting your conversa /ask What does the `retry` utility in src/utils do? ``` -The `/refine` command *(v1.0.70+)* rewrites a rough, stream-of-consciousness prompt into a clear, structured one before sending it to the agent: +The `/refine` command rewrites a rough, stream-of-consciousness prompt into a clear, structured one before sending it to the agent: ``` /refine @@ -713,13 +707,13 @@ The `/context` command shows a visualization of the current conversation's conte /context ``` -The `/usage` command displays session metrics such as the number of tokens consumed, API calls made, and any quota information for the current session. In v1.0.64+, `/usage` also shows per-model token totals when you have used multiple models in a session: +The `/usage` command displays session metrics such as the number of tokens consumed, API calls made, and any quota information for the current session, including per-model token totals when you have used multiple models in a session: ``` /usage ``` -**`/limits predict`** *(v1.0.76+)*: Usage-based billing users can run `/limits predict` to get a suggested AI-credit limit for the current session, based on the credit consumption of similar past sessions. This helps you set a realistic `sessionLimits` value ahead of a large task instead of guessing: +**`/limits predict`**: Usage-based billing users can run `/limits predict` to get a suggested AI-credit limit for the current session, based on the credit consumption of similar past sessions. This helps you set a realistic `sessionLimits` value ahead of a large task instead of guessing: ``` /limits predict @@ -733,9 +727,9 @@ The `/compact` command summarizes the conversation history to free up context wi > **Note**: Skills remain loaded and effective after `/compact`. You do not need to re-invoke them after compacting. -> **ACP sessions (v1.0.39+)**: The `/compact`, `/context`, `/usage`, and `/env` commands are now available in ACP (Agent Coordination Protocol) sessions, allowing remote ACP clients to surface session details and manage context from within their own automated workflows. +> **ACP sessions**: The `/compact`, `/context`, `/usage`, and `/env` commands are available in ACP (Agent Coordination Protocol) sessions, allowing remote ACP clients to surface session details and manage context from within their own automated workflows. -The `/statusline` command (with `/footer` as an alias) lets you control which items appear in the terminal status bar. You can show or hide individual indicators like the working directory, current branch, effort level, context window usage, quota, and **active account username** (v1.0.43+). The **changes** toggle shows a running count of added/removed lines for the session — useful when tracking the scope of an ongoing edit. In v1.0.65+, there is also an opt-in **CI check status** indicator that shows the passing/running/failing state of CI checks for the current branch — enable it from the `/statusline` menu: +The `/statusline` command (with `/footer` as an alias) lets you control which items appear in the terminal status bar. You can show or hide individual indicators like the working directory, current branch, effort level, context window usage, quota, and **active account username**. The **changes** toggle shows a running count of added/removed lines for the session — useful when tracking the scope of an ongoing edit. There is also an opt-in **CI check status** indicator that shows the passing/running/failing state of CI checks for the current branch — enable it from the `/statusline` menu: ``` /statusline # show the statusline configuration menu @@ -749,9 +743,7 @@ The `/keep-alive` command prevents the system from sleeping while Copilot CLI is /keep-alive # toggle keep-alive on or off ``` -> **Note**: `/keep-alive` was previously an experimental feature. As of v1.0.36, it is available without enabling experimental mode. - -The `/allow-all` command (also accessible as `/yolo`) enables autopilot mode, where the agent runs all tools without asking for confirmation. It now supports `on`, `off`, and `show` subcommands: +The `/allow-all` command (also accessible as `/yolo`) enables autopilot mode, where the agent runs all tools without asking for confirmation. It supports `on`, `off`, and `show` subcommands: ``` /allow-all on # enable allow-all mode @@ -761,9 +753,9 @@ The `/allow-all` command (also accessible as `/yolo`) enables autopilot mode, wh > **Note**: `/allow-all on` permissions persist after `/clear` starts a new session, so you don't need to re-enable it each time. -> **ACP clients (v1.0.39+)**: ACP clients can also toggle allow-all mode programmatically via session configuration, without issuing a slash command. This is useful for automated pipelines that drive Copilot CLI through the ACP protocol. +> **ACP clients**: ACP clients can also toggle allow-all mode programmatically via session configuration, without issuing a slash command. This is useful for automated pipelines that drive Copilot CLI through the ACP protocol. -The `/autopilot` command (v1.0.45+) is a quick in-session toggle that switches between **interactive mode** (where the agent pauses to ask for confirmation before tool use) and **autopilot mode** (where it runs autonomously). Unlike `/allow-all` which specifically controls whether tool permissions are required, `/autopilot` toggles the overall agent mode: +The `/autopilot` command is a quick in-session toggle that switches between **interactive mode** (where the agent pauses to ask for confirmation before tool use) and **autopilot mode** (where it runs autonomously). Unlike `/allow-all` which specifically controls whether tool permissions are required, `/autopilot` toggles the overall agent mode: ``` /autopilot # toggle between interactive and autopilot modes @@ -771,13 +763,13 @@ The `/autopilot` command (v1.0.45+) is a quick in-session toggle that switches b Use `/autopilot` when you want to flip between supervised and unsupervised operation mid-session without typing out the full `/allow-all on` or `/allow-all off` commands. -> **Enhanced autopilot (v1.0.64+)**: When autopilot mode is active — including when launched with `--autopilot` at startup or during automatic continuation turns — the agent automatically handles elicitation dialogs, `ask_user` prompts, sampling requests, and permission prompts without surfacing them as interactive dialogs. This means long-running automated sessions can proceed end-to-end without manual confirmation steps. +> **Enhanced autopilot**: When autopilot mode is active — including when launched with `--autopilot` at startup or during automatic continuation turns — the agent automatically handles elicitation dialogs, `ask_user` prompts, sampling requests, and permission prompts without surfacing them as interactive dialogs. This means long-running automated sessions can proceed end-to-end without manual confirmation steps. -> **Auto allow-all mode (v1.0.69+)**: In addition to the standard allow-all mode (which approves everything), the CLI now supports an **auto allow-all** mode that uses an LLM judge to evaluate each tool request. When enabled, the judge automatically approves requests it evaluates as acceptable, and asks you for manual confirmation only for requests it considers risky. This gives you a middle ground between full autopilot and fully supervised operation — most routine actions proceed automatically while unusual or potentially dangerous actions still surface for your review. As of v1.0.69-3, this mode requires experimental features to be enabled — use `/experimental on` or start the CLI with `--experimental` — then activate it with `/allow-all auto`. The previous `AUTO_APPROVAL` environment variable approach has been removed in favour of experimental mode. +> **Auto allow-all mode**: In addition to the standard allow-all mode (which approves everything), the CLI supports an **auto allow-all** mode that uses an LLM judge to evaluate each tool request. When enabled, the judge automatically approves requests it evaluates as acceptable, and asks you for manual confirmation only for requests it considers risky. This gives you a middle ground between full autopilot and fully supervised operation — most routine actions proceed automatically while unusual or potentially dangerous actions still surface for your review. This mode requires experimental features to be enabled — use `/experimental on` or start the CLI with `--experimental` — then activate it with `/allow-all auto`. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you previously relied on the `AUTO_APPROVAL` environment variable for this. -> **Read-only `gh` CLI commands (v1.0.46+)**: Read-only `gh` commands — such as `gh issue list`, `gh pr view`, `gh run status`, and other commands that don't write to GitHub — are **automatically approved** without a permission prompt. Only commands that write to GitHub (like creating issues, merging PRs) still require explicit approval. This reduces friction during exploratory sessions where you frequently check issue or PR status. +> **Read-only `gh` CLI commands**: Read-only `gh` commands — such as `gh issue list`, `gh pr view`, `gh run status`, and other commands that don't write to GitHub — are **automatically approved** without a permission prompt. Only commands that write to GitHub (like creating issues, merging PRs) still require explicit approval. This reduces friction during exploratory sessions where you frequently check issue or PR status. -The `/permissions` command *(v1.0.78+)* opens an interactive picker for switching between approval modes mid-session. Instead of typing `/allow-all on` or `/autopilot`, `/permissions` gives you a visual overview of available modes — interactive, autopilot, auto (LLM-judged), and plan — and lets you switch with a single keypress: +The `/permissions` command opens an interactive picker for switching between approval modes mid-session. Instead of typing `/allow-all on` or `/autopilot`, `/permissions` gives you a visual overview of available modes — interactive, autopilot, auto (LLM-judged), and plan — and lets you switch with a single keypress: ``` /permissions @@ -795,7 +787,7 @@ Accepted values are `low`, `medium`, and `high`. You can also set a default via ### CLI Startup Flags -The `-C ` flag changes the working directory before starting, similar to `git -C` (v1.0.42+). This is useful for scripts or aliases that need to start Copilot CLI in a specific project directory without a separate `cd`: +The `-C ` flag changes the working directory before starting, similar to `git -C`. This is useful for scripts or aliases that need to start Copilot CLI in a specific project directory without a separate `cd`: ```bash copilot -C ~/projects/my-repo # start in a different directory @@ -812,7 +804,7 @@ copilot --plan # start in plan mode (propose without executing) This is useful in scripts or CI pipelines where you want the CLI to immediately begin working in a specific mode without an interactive prompt. -**Plan-then-implement (v1.0.79+)**: Combine `--plan` with `--mode autopilot` to have the agent draft a plan first and then implement it without waiting for approval, instead of pausing after the plan for manual confirmation: +**Plan-then-implement**: Combine `--plan` with `--mode autopilot` to have the agent draft a plan first and then implement it without waiting for approval, instead of pausing after the plan for manual confirmation: ```bash copilot --plan --mode autopilot "Add rate limiting to the API" @@ -828,7 +820,7 @@ copilot --autopilot --max-autopilot-continues 10 "Refactor the authentication mo Set it higher for long-running tasks, or lower for tasks where you want more frequent checkpoints. Setting it to `0` disables automatic continuation entirely. -The `--sandbox` and `--no-sandbox` flags *(v1.0.70+)* turn the OS-level shell sandbox on or off for the current session only, without permanently changing your saved sandbox setting. This is useful with `-p` (prompt mode) when you need to temporarily adjust sandbox behavior for a specific automated task: +The `--sandbox` and `--no-sandbox` flags turn the OS-level shell sandbox on or off for the current session only, without permanently changing your saved sandbox setting. This is useful with `-p` (prompt mode) when you need to temporarily adjust sandbox behavior for a specific automated task: ```bash copilot --sandbox -p "Run the full test suite and fix any failures" @@ -837,19 +829,17 @@ copilot --no-sandbox -p "Set up development environment with system tools" These flags apply only to the current invocation — your persisted sandbox preference remains unchanged. -**`allowDevToolAccess` sandbox setting** *(v1.0.78+ as `allowDevToolCaches`, renamed to `allowDevToolAccess` in v1.0.79 — breaking change)*: When the sandbox is enabled, this setting grants sandboxed builds access to toolchain caches, registries, config files, and installs (npm cache, pip cache, Go module cache, etc.) so builds work without extra setup. Set it to `false` in `/settings` to opt out if you want a stricter sandbox that blocks all toolchain access. +**`allowDevToolAccess` sandbox setting**: When the sandbox is enabled, this setting grants sandboxed builds access to toolchain caches, registries, config files, and installs (npm cache, pip cache, Go module cache, etc.) so builds work without extra setup. Set it to `false` in `/settings` to opt out if you want a stricter sandbox that blocks all toolchain access. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you have an older `allowDevToolCaches` value configured. -> **Breaking change (v1.0.79)**: The setting was renamed from `allowDevToolCaches` to `allowDevToolAccess`. If you previously set `allowDevToolCaches` to `false` to opt out, update your `settings.json` to use `allowDevToolAccess` — the old key is silently ignored. +**Sandbox auth settings**: The `/sandbox` configuration dialog groups git, `gh`, and (on macOS) keychain settings under an **Auth** tab, backed by the `sandbox.auth.git` and `sandbox.auth.gh` settings keys. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you have the older `sandbox.gitAuth`/`sandbox.ghAuth` keys configured. -**Sandbox auth settings** *(v1.0.79-8+, breaking change)*: The `/sandbox` configuration dialog now groups git, `gh`, and (on macOS) keychain settings under a new **Auth** tab. The underlying settings keys moved from `sandbox.gitAuth`/`sandbox.ghAuth` to `sandbox.auth.git`/`sandbox.auth.gh`. There is no automatic migration — the old keys are silently ignored in settings files, and SDK requests that still send them are rejected as invalid. Update any saved configuration to the new key names. +**`worktreeBaseRef` setting**: Controls whether `/worktree`, `/worktree new`, and the `--worktree` startup flag create the new worktree from `HEAD` or from the remote default branch. All three default to `HEAD`. Set this in `/settings` if you want worktrees to branch from the remote default instead. -**`worktreeBaseRef` setting** *(v1.0.79-8+)*: Controls whether `/worktree`, `/worktree new`, and the `--worktree` startup flag create the new worktree from `HEAD` or from the remote default branch. All three now default to `HEAD`; previously `--worktree` defaulted to starting from the remote default branch. Set this in `/settings` if you want worktrees to branch from the remote default instead. - -> **Breaking change — sandbox network isolation (v1.0.83+)**: On macOS and Linux, sandboxed commands can no longer reach services running on your own machine, including a server the sandboxed command itself starts on `127.0.0.1`. This means test suites that bind a local port will fail inside the sandbox. Turn on **Allow local network** in `/sandbox` to restore access to localhost. On Linux, sandboxing also now requires `slirp4netns`, `nsenter`, `iptables`, `ip6tables`, `iptables-restore`, and `ip6tables-restore` on `PATH` — install these if sandboxed commands start failing to launch. Additionally, Linux sandboxes now restrict network egress to the configured HTTP(S) proxy when one is set; this proxy mode requires `slirp4netns`, `util-linux` 2.35+, `iptables`, and `/dev/net/tun` access. +**Sandbox network isolation**: On macOS and Linux, sandboxed commands cannot reach services running on your own machine, including a server the sandboxed command itself starts on `127.0.0.1`. This means test suites that bind a local port will fail inside the sandbox. Turn on **Allow local network** in `/sandbox` to restore access to localhost. On Linux, sandboxing also requires `slirp4netns`, `nsenter`, `iptables`, `ip6tables`, `iptables-restore`, and `ip6tables-restore` on `PATH` — install these if sandboxed commands start failing to launch. Additionally, Linux sandboxes restrict network egress to the configured HTTP(S) proxy when one is set; this proxy mode requires `slirp4netns`, `util-linux` 2.35+, `iptables`, and `/dev/net/tun` access. The `--attachment` flag (available in prompt mode, `-p`) lets you attach files — images or native documents — to the initial prompt in non-interactive mode: -**Browser-based OAuth login** *(v1.0.77+)*: `copilot login` now defaults to the browser (web) flow on local interactive terminals. A browser tab opens, you authenticate with GitHub, and the CLI is authorized without typing a device code. On remote or headless terminals (SSH sessions, CI), device code remains the default. You can force a specific flow with `--web-flow` or `--device-code`, or choose interactively with the `/login` command: +**Browser-based OAuth login**: `copilot login` defaults to the browser (web) flow on local interactive terminals. A browser tab opens, you authenticate with GitHub, and the CLI is authorized without typing a device code. On remote or headless terminals (SSH sessions, CI), device code remains the default. You can force a specific flow with `--web-flow` or `--device-code`, or choose interactively with the `/login` command: ```bash copilot login # browser flow on local terminals, device code on remote/headless @@ -906,7 +896,7 @@ echo 'source ~/.copilot-completion.bash' >> ~/.bashrc ### Vim Mode -**Vim mode is now available to everyone** *(v1.0.84+)*: Turn on modal editing in the composer with `/vim`, or set `editorMode` to `vim` in your settings to enable it by default for every session. The current mode (insert or normal) is shown while you type, so you always know which mode is active: +**Vim mode is available to everyone**: Turn on modal editing in the composer with `/vim`, or set `editorMode` to `vim` in your settings to enable it by default for every session. The current mode (insert or normal) is shown while you type, so you always know which mode is active: ``` /vim # toggle Vim modal editing for the current session @@ -914,7 +904,7 @@ echo 'source ~/.copilot-completion.bash' >> ~/.bashrc ### Managing Plugin Components from the CLI -*(v1.0.84+)* Component-specific list and enable/disable commands replace the older cross-kind `copilot plugins` flags. Use `copilot instruction list` and `copilot lsp list` to see loaded instructions and LSP servers, and use `enable`/`disable` on the dedicated `copilot plugin`, `copilot mcp`, and `copilot skill` commands instead of the retired `copilot plugins enable/disable --plugin|--mcp|--skill` flags: +Component-specific list and enable/disable commands are the current way to manage plugin components. Use `copilot instruction list` and `copilot lsp list` to see loaded instructions and LSP servers, and use `enable`/`disable` on the dedicated `copilot plugin`, `copilot mcp`, and `copilot skill` commands: ```bash copilot instruction list # list currently loaded instructions @@ -924,11 +914,11 @@ copilot mcp disable my-server # disable a specific MCP server copilot skill enable my-skill # enable a specific skill ``` -> **Breaking change (v1.0.84+)**: The cross-kind `--kind`, `--scope`, `--mcp`, and `--skill` flags have been removed from `copilot plugins`. `copilot plugins list` is now an alias of `copilot plugin list` and reports only plugins — not MCP servers, skills, instructions, or LSP servers. Scripts that installed skills with `copilot plugins install --skill [--scope project]` should switch to `copilot skill add [--project]`, and scripts reading `.plugins` from `copilot plugins list --json` should expect a flat array instead of the previous `{ plugins, errors }` object. +See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you have scripts using the older cross-kind `copilot plugins` flags. ### The `/config` Sidebar -*(v1.0.84+)* Run `/config` to open a dedicated sidebar configuration screen inside the CLI, giving you a browsable view of your active settings without leaving the terminal session or hand-editing `config.json`: +Run `/config` to open a dedicated sidebar configuration screen inside the CLI, giving you a browsable view of your active settings without leaving the terminal session or hand-editing `config.json`: ``` /config @@ -936,15 +926,31 @@ copilot skill enable my-skill # enable a specific skill ### Sandbox Network Allow/Deny Rules -*(v1.0.84+)* `/sandbox` now supports per-host network allow/deny rules that layer on top of your configured upstream proxy, instead of replacing it. This lets you permit or block specific hosts for sandboxed commands without reconfiguring your whole proxy setup — useful when a sandboxed build or test needs to reach one extra domain (like a package registry mirror) while keeping the rest of your network policy intact. +`/sandbox` supports per-host network allow/deny rules that layer on top of your configured upstream proxy, instead of replacing it. This lets you permit or block specific hosts for sandboxed commands without reconfiguring your whole proxy setup — useful when a sandboxed build or test needs to reach one extra domain (like a package registry mirror) while keeping the rest of your network policy intact. ### Memory and Session Import -*(v1.0.84+)* New session and memory import commands accept the semantic JSONL interchange format, making it possible to bring saved session history or memory entries into Copilot CLI from an external export rather than starting from scratch. +Session and memory import commands accept the semantic JSONL interchange format, making it possible to bring saved session history or memory entries into Copilot CLI from an external export rather than starting from scratch. -### Command-Line Parsing Rewrite +### Command-Line Parsing -*(v1.0.84+)* Command-line parsing moved from Commander to a Rust-based grammar that mirrors what the CLI actually parses, which also generates shell completions directly from that grammar — so `copilot ` now offers root flags alongside subcommands, and each subcommand only shows its own options. As a result of this change, some error and help wording changed, `copilot login --host` now works correctly, and `--max-autopilot-continues` no longer accepts scientific notation as a value. +Command-line parsing is handled by a Rust-based grammar that mirrors what the CLI actually parses, which also generates shell completions directly from that grammar — so `copilot ` offers root flags alongside subcommands, and each subcommand only shows its own options. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) for behavior changes from the previous Commander-based parser. + +## Compatibility and Migration Notes + +This section collects settings and behaviors that **changed or were renamed** in past releases. Check here if something you configured previously stopped working, or if you're auditing an older config file — everything above describes current behavior and does not require reading this section first. + +- **`~/.claude/` agents and skills are not loaded.** Only `~/.claude/settings.json` is read for configuration; custom agents, skills, and commands placed in `~/.claude/` are ignored. Move them to `~/.copilot/agents/`, `~/.copilot/skills/`, `~/.agents/skills/`, or your repository's `.github/agents/` / `.github/skills/`. +- **`/model` now scopes to the current session only.** Previously it changed both the session model and your global default together. Use `/config model` to change the default for future sessions. +- **`allowDevToolCaches` was renamed to `allowDevToolAccess`.** If your settings file still sets `allowDevToolCaches`, it is silently ignored — update it to `allowDevToolAccess`. +- **Sandbox auth settings moved from `sandbox.gitAuth`/`sandbox.ghAuth` to `sandbox.auth.git`/`sandbox.auth.gh`.** There is no automatic migration; the old keys are silently ignored, and SDK requests that still send them are rejected as invalid. +- **`worktreeBaseRef` now defaults to `HEAD` for all worktree-creation paths.** The `--worktree` startup flag previously defaulted to branching from the remote default branch instead. +- **Sandbox network isolation on macOS/Linux blocks localhost by default.** Sandboxed commands — including a server the sandboxed command itself starts on `127.0.0.1` — can no longer reach services on your own machine. Turn on **Allow local network** in `/sandbox` if your test suite binds a local port. Linux sandboxing also requires `slirp4netns`, `nsenter`, `iptables`, `ip6tables`, `iptables-restore`, and `ip6tables-restore` on `PATH`. +- **`copilot plugins` lost its cross-kind flags.** The `--kind`, `--scope`, `--mcp`, and `--skill` flags were removed; `copilot plugins list` is now an alias of `copilot plugin list` and reports only plugins. Scripts using `copilot plugins install --skill [--scope project]` should switch to `copilot skill add [--project]`, and scripts reading `.plugins` from `copilot plugins list --json` should expect a flat array instead of the previous `{ plugins, errors }` object. +- **Auto allow-all mode requires experimental mode.** The previous `AUTO_APPROVAL` environment variable approach was removed in favor of `/experimental on` (or `--experimental`) plus `/allow-all auto`. +- **Ctrl+D no longer queues messages.** It now uses its default terminal behavior; use **Ctrl+Q** or **Ctrl+Enter** to queue a message instead. +- **The CLI's command-line parser was rewritten** (moving off Commander to a Rust-based grammar). As a result, some error and help wording changed, `copilot login --host` now works correctly, and `--max-autopilot-continues` no longer accepts scientific notation as a value. +- **Model availability changes over time.** The model picker periodically retires older models; if a model you previously pinned in a custom agent or config disappears from `/model`, switch to a current model or a [family alias](#model-picker) instead. ## Common Questions diff --git a/website/src/content/docs/learning-hub/installing-and-using-plugins.md b/website/src/content/docs/learning-hub/installing-and-using-plugins.md index 86de8206..45201338 100644 --- a/website/src/content/docs/learning-hub/installing-and-using-plugins.md +++ b/website/src/content/docs/learning-hub/installing-and-using-plugins.md @@ -3,7 +3,7 @@ title: 'Installing and Using Plugins' description: 'Learn how to find, install, and manage plugins that extend GitHub Copilot CLI with reusable agents, skills, hooks, and integrations.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-09-12 +lastUpdated: 2026-09-22 relatedArticles: - ./building-custom-agents.md - ./creating-effective-skills.md @@ -28,9 +28,9 @@ A plugin bundles one or more of the following components: | **Hooks** | Event handlers that intercept agent behavior | `hooks.json` or `hooks/` | | **MCP Servers** | Model Context Protocol integrations for external tools | `.mcp.json` or `.github/mcp.json` | | **LSP Servers** | Language Server Protocol integrations | `lsp.json` or `.github/lsp.json` | -| **Extensions** | IDE extensions installable via the plugin marketplace (v1.0.62+) | `extensions/` | +| **Extensions** | IDE extensions installable via the plugin marketplace | `extensions/` | -> *(v1.0.79+)* Agent Plugins spec plugins can also ship canvas extensions under a `com.github.copilot/extensions/` directory inside the plugin, so a single plugin package can bundle agents, skills, and canvas extensions together. +Agent Plugins spec plugins can also ship canvas extensions under a `com.github.copilot/extensions/` directory inside the plugin, so a single plugin package can bundle agents, skills, and canvas extensions together. A plugin might include all of these or just one — for example, a plugin could provide a single specialized agent, or an entire development toolkit with multiple agents, skills, hooks, and MCP server configurations working together. @@ -155,9 +155,9 @@ To automatically register an additional marketplace for everyone working in a re } ``` -With this in place, team members automatically get the `my-org-plugins` marketplace available without running a separate `marketplace add` command. This replaces the older `marketplaces` setting, which was removed in v1.0.16. +With this in place, team members automatically get the `my-org-plugins` marketplace available without running a separate `marketplace add` command. -**Auto-updating team marketplaces** *(v1.0.79+)*: Set `"autoUpdate": true` on an `extraKnownMarketplaces` entry to have that marketplace's plugins update automatically at the start of each session, without requiring a manual `copilot plugin marketplace update` or `copilot plugin update`: +**Auto-updating team marketplaces**: Set `"autoUpdate": true` on an `extraKnownMarketplaces` entry to have that marketplace's plugins update automatically at the start of each session, without requiring a manual `copilot plugin marketplace update` or `copilot plugin update`: ```json { @@ -175,7 +175,7 @@ This is useful for internal marketplaces where you want every team member to alw ### Pinning a Marketplace to a Specific Commit -*(v1.0.70+)* To ensure reproducibility and prevent unintended updates, you can pin a marketplace to an exact commit SHA using the `sha` field in the source configuration: +To ensure reproducibility and prevent unintended updates, you can pin a marketplace to an exact commit SHA using the `sha` field in the source configuration: ```json { @@ -235,14 +235,12 @@ copilot plugin marketplace update copilot plugin uninstall my-plugin ``` -> **Auto-update for first-party plugins** *(v1.0.78+)*: Plugins sourced from the official `copilot-plugins` marketplace automatically update to their latest version at the start of each session. You do not need to run `copilot plugin update` for first-party plugins — updates are applied silently on startup. Community plugins from `awesome-copilot` and other marketplace registries still require a manual `copilot plugin update` command. +> **Auto-update for first-party plugins**: Plugins sourced from the official `copilot-plugins` marketplace automatically update to their latest version at the start of each session. You do not need to run `copilot plugin update` for first-party plugins — updates are applied silently on startup. Community plugins from `awesome-copilot` and other marketplace registries still require a manual `copilot plugin update` command. -> **Component-specific commands (v1.0.84+)**: Individual component kinds now have their own dedicated CLI commands instead of relying on cross-kind flags on `copilot plugins`. Use `copilot instruction list` and `copilot lsp list` to inspect loaded instructions and LSP servers, and use `enable`/`disable` directly on `copilot plugin`, `copilot mcp`, and `copilot skill` (for example, `copilot skill disable my-skill`) instead of the removed `copilot plugins enable/disable --plugin|--mcp|--skill` flags. Installing a standalone skill now uses `copilot skill add [--project]` in place of the retired `copilot plugins install --skill [--scope project]`. +Individual component kinds have their own dedicated CLI commands. Use `copilot instruction list` and `copilot lsp list` to inspect loaded instructions and LSP servers, and use `enable`/`disable` directly on `copilot plugin`, `copilot mcp`, and `copilot skill` (for example, `copilot skill disable my-skill`). Install a standalone skill with `copilot skill add [--project]`. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) if you have scripts using the older cross-kind `copilot plugins` flags. ### Enabling and Disabling Plugin Components -> **Breaking change (v1.0.81+)**: The `/plugins` command has been **removed**. Its functionality moved to dedicated commands: `/plugin` (plugin dashboard), `/mcp` (MCP servers), and `/skills` (skills), with `/subagents` for custom agents and `/instructions` for instructions. - Run `/plugin` (or `copilot plugin list` in non-interactive mode) to see **enable/disable toggles** for individual plugin components. You can turn off specific agents, instructions, hooks, LSP servers, or entire plugins without uninstalling them: ``` @@ -251,11 +249,9 @@ Run `/plugin` (or `copilot plugin list` in non-interactive mode) to see **enable This opens an interactive list where each installed plugin and its components are shown with a toggle. Disabling a component hides it from Copilot without removing it from disk — useful for temporarily deactivating a hook that is too noisy, or turning off a plugin's instructions when working on a different type of project. Re-enable the component at any time from the same `/plugin` menu. -*(v1.0.81+)* `/plugin` also flags installed plugins and marketplaces that have a newer version available upstream, and offers an **Update** action to pull the latest version directly from the dashboard. +`/plugin` also flags installed plugins and marketplaces that have a newer version available upstream, and offers an **Update** action to pull the latest version directly from the dashboard. -> **Note**: Enabling and disabling hooks and LSP servers individually is temporarily unavailable following the `/plugins` removal — those toggles previously lived only in the retired dashboard. - -> **Dashboard available to everyone (v1.0.81+)**: The plugins dashboard (`/plugin`, `/mcp`, and `/skills`) is now on for all users by default. If you need to opt out, set `PLUGINS_DASHBOARD=false`, which also restores the legacy `copilot plugins` command. This opt-out was later removed in the same release, along with the legacy skills picker it kept alive — `/skills`, bare `/mcp`, and `/mcp show` (with no server name) always open the dashboard now, and `/mcp config` opens the dedicated MCP wizard. +The plugins dashboard (`/plugin`, `/mcp`, and `/skills`) is on for all users by default; `/skills`, bare `/mcp`, and `/mcp show` (with no server name) open the dashboard, and `/mcp config` opens the dedicated MCP wizard. See [Compatibility and Migration Notes](#compatibility-and-migration-notes) for the history of the retired `/plugins` command and its dashboard opt-out. ### Loading Plugins from a Local Directory @@ -311,7 +307,7 @@ See [Using the Copilot Coding Agent](../using-copilot-coding-agent/) for details ## Agent Plugins Standard Compatibility -*(v1.0.74+)* GitHub Copilot CLI supports **Open Plugin Spec v1** plugin manifests, in addition to its own `plugin.json` format. This means plugins authored for other AI tools or platforms using the Open Plugin Spec standard can be installed and used in Copilot CLI without any modification. +GitHub Copilot CLI supports **Open Plugin Spec v1** plugin manifests, in addition to its own `plugin.json` format. This means plugins authored for other AI tools or platforms using the Open Plugin Spec standard can be installed and used in Copilot CLI without any modification. That standard has since matured: on August 6, 2026, [**Agent Plugins 1.0**](https://agent-plugins.org/) launched as the open, cross-tool specification for this portable packaging format, with VS Code adopting it alongside Copilot CLI. A plugin that follows the standard is just a directory containing a `plugin.json` manifest, skills under `skills/`, and MCP server configuration in `mcp.json` — no per-tool repackaging required. VS Code and Copilot CLI both read the portable parts of the package, and each also reads its own tool-specific components from a dedicated namespace (for example, `com.github.copilot/` for Copilot-specific agents, hooks, and canvas extensions). A client that doesn't recognize a given namespace simply ignores it, so one plugin package can stay portable while still bringing custom agents, slash commands, and hooks to every tool that supports the namespace. @@ -340,6 +336,15 @@ This is useful for plugins that bundle dedicated tooling (for example, a databas - **Use plugins for team standards** — publish an internal plugin to ensure every team member has the same agents, skills, and hooks - **Remove unused plugins** — declutter with `copilot plugin uninstall` to keep your environment clean +## Compatibility and Migration Notes + +This section collects behaviors that **changed or were renamed** in past releases. Check here if a command you remember stopped working — everything above describes current behavior. + +- **The `/plugins` command was removed.** Its functionality moved to dedicated commands: `/plugin` (plugin dashboard), `/mcp` (MCP servers), and `/skills` (skills), with `/subagents` for custom agents and `/instructions` for instructions. The plugins dashboard is now on by default for everyone; there is no supported way to opt back into the legacy `copilot plugins` command. +- **`copilot plugins` lost its cross-kind flags.** The `--kind`, `--scope`, `--mcp`, and `--skill` flags were removed. `copilot plugins list` is now an alias of `copilot plugin list` and reports only plugins. Scripts using `copilot plugins install --skill [--scope project]` should switch to `copilot skill add [--project]`, and scripts reading `.plugins` from `copilot plugins list --json` should expect a flat array instead of the previous `{ plugins, errors }` object. +- **The older top-level `marketplaces` setting was removed** in favor of `extraKnownMarketplaces` in `.github/copilot-settings.json` (or `config.json`). +- **Installing plugins directly from a GitHub repository URL, raw URL, or local file path is deprecated** and will be removed in a future release — use marketplace-based installation (`copilot plugin install name@marketplace`) instead. + ## Common Questions **Q: Do plugins work with the coding agent on GitHub.com?** diff --git a/website/src/content/docs/learning-hub/understanding-mcp-servers.md b/website/src/content/docs/learning-hub/understanding-mcp-servers.md index 268501f7..682448ff 100644 --- a/website/src/content/docs/learning-hub/understanding-mcp-servers.md +++ b/website/src/content/docs/learning-hub/understanding-mcp-servers.md @@ -3,7 +3,7 @@ title: 'Understanding MCP Servers' description: 'Learn how Model Context Protocol servers extend GitHub Copilot with access to external tools, databases, and APIs.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-09-05 +lastUpdated: 2026-09-22 estimatedReadingTime: '8 minutes' tags: - mcp @@ -66,7 +66,7 @@ MCP servers are configured per-workspace. GitHub Copilot CLI discovers server de | File | Scope | Notes | |------|-------|-------| | `.mcp.json` | Repository root | Preferred for repo-shared configuration | -| `.github/mcp.json` | Repository `.github/` folder | Auto-loaded workspace config (v1.0.61+) | +| `.github/mcp.json` | Repository `.github/` folder | Auto-loaded workspace config | | `.vscode/mcp.json` | VS Code workspace | VS Code–compatible workspace config | | `devcontainer.json` | Dev container | Available when running inside a container | @@ -92,11 +92,11 @@ Example `.mcp.json` or `.vscode/mcp.json`: } ``` -> **Protocol update (v1.0.81+)**: GitHub Copilot CLI, the SDK, IDE integrations, and in-memory clients now support the **MCP 2026-07-28 specification**, keeping compatibility current with the latest Model Context Protocol servers as they adopt the new spec revision. +GitHub Copilot CLI, the SDK, IDE integrations, and in-memory clients support the **MCP 2026-07-28 specification**, keeping compatibility current with the latest Model Context Protocol servers as they adopt the new spec revision. ### Installing MCP Servers from the Registry -GitHub Copilot CLI provides a registry-based install flow that lets you browse and install MCP servers with guided configuration — no manual JSON editing required. In v1.0.64+, use the `/mcp registry` sub-command to browse available servers: +GitHub Copilot CLI provides a registry-based install flow that lets you browse and install MCP servers with guided configuration — no manual JSON editing required. Use the `/mcp registry` sub-command to browse available servers: ``` /mcp registry @@ -122,11 +122,11 @@ This guided flow is the recommended way to add new MCP servers, especially for s **type** (remote servers): The transport type for remote MCP servers (`http` or `sse`). This field can now be omitted — the CLI defaults to `http` when no type is specified, simplifying remote server configuration. -**deferTools** *(optional, v1.0.63+)*: When set to `false`, the server's tools are always available even when tool search is enabled. By default, tool search can hide rarely-used MCP tools to reduce context noise; setting `deferTools: false` on a server prevents its tools from being deferred, keeping them permanently in the tool list. +**deferTools** *(optional)*: When set to `false`, the server's tools are always available even when tool search is enabled. By default, tool search can hide rarely-used MCP tools to reduce context noise; setting `deferTools: false` on a server prevents its tools from being deferred, keeping them permanently in the tool list. ### Allowing MCP Server Instructions -By default, Copilot CLI limits which MCP server instructions are injected into the system prompt, to avoid noisy or unexpected instructions from servers you may not have fully reviewed. You can opt in to include instructions from **all** connected MCP servers with the `--allow-all-mcp-server-instructions` flag *(v1.0.66+)*: +By default, Copilot CLI limits which MCP server instructions are injected into the system prompt, to avoid noisy or unexpected instructions from servers you may not have fully reviewed. You can opt in to include instructions from **all** connected MCP servers with the `--allow-all-mcp-server-instructions` flag: ```bash copilot --allow-all-mcp-server-instructions @@ -151,7 +151,7 @@ These are especially useful for plugins and installer scripts that need to self- ### Reading MCP Server Resources via Session RPCs -*(v1.0.70+)* In addition to config management, GitHub Copilot CLI exposes **paginated session RPCs** for reading resources exposed by connected MCP servers. These let agents and tooling access server-provided resource lists and templates without needing direct MCP protocol access: +In addition to config management, GitHub Copilot CLI exposes **paginated session RPCs** for reading resources exposed by connected MCP servers. These let agents and tooling access server-provided resource lists and templates without needing direct MCP protocol access: | RPC | Description | |-----|-------------| @@ -215,7 +215,7 @@ Some MCP servers require authentication to connect to protected resources. GitHu > **Tip**: If your MCP server uses OAuth with Dynamic Client Registration but hosts its authorization metadata at a non-standard URL (as some enterprise servers like Atlassian Rovo do), Copilot CLI handles this automatically. -> **Client ID Metadata Document support (v1.0.83+)**: Copilot CLI can now sign in to MCP servers using a **Client ID Metadata Document (CIMD)** for OAuth, an alternative to Dynamic Client Registration where the client's identity is published as a metadata document at a URL instead of being registered ahead of time with the authorization server. +Copilot CLI can sign in to MCP servers using a **Client ID Metadata Document (CIMD)** for OAuth, an alternative to Dynamic Client Registration where the client's identity is published as a metadata document at a URL instead of being registered ahead of time with the authorization server. ## How Agents Use MCP Tools @@ -294,7 +294,7 @@ MCP server SDKs are available in [Python](https://github.com/modelcontextprotoco When an MCP server fails to start or loses its connection, Copilot CLI surfaces a warning with actionable details to help you diagnose the problem quickly. -**Failure warnings include stderr output** (v1.0.42+): If your MCP server prints error messages to stderr (e.g., missing environment variables, connection refused, import errors), those messages are now included directly in the CLI warning. This means you usually see the root cause without needing to run the server manually. +**Failure warnings include stderr output**: If your MCP server prints error messages to stderr (e.g., missing environment variables, connection refused, import errors), those messages are included directly in the CLI warning. This means you usually see the root cause without needing to run the server manually. For example, a PostgreSQL server that can't connect because `DATABASE_URL` is not set will show: @@ -311,7 +311,7 @@ For example, a PostgreSQL server that can't connect because `DATABASE_URL` is no /mcp show postgres # inspect a specific server ``` -**Viewing attached servers with `/mcp list`** (v1.0.69+): Use `/mcp list` to see which MCP servers are currently attached to your session and their status. Unlike `/mcp show` (which shows all configured servers), `/mcp list` focuses on what's active right now and can run **while the agent is working** — useful for checking server status mid-turn without interrupting the agent: +**Viewing attached servers with `/mcp list`**: Use `/mcp list` to see which MCP servers are currently attached to your session and their status. Unlike `/mcp show` (which shows all configured servers), `/mcp list` focuses on what's active right now and can run **while the agent is working** — useful for checking server status mid-turn without interrupting the agent: ``` /mcp list # show servers attached to this session @@ -319,7 +319,7 @@ For example, a PostgreSQL server that can't connect because `DATABASE_URL` is no You can also open the `/mcp` manager while the agent is working to toggle servers on or off mid-turn. Add, edit, delete, and re-auth actions wait until the turn finishes, but enabling or disabling a server takes effect immediately. -**Toggling servers on and off** (v1.0.66+): From the `/mcp` list view, you can **enable or disable individual MCP servers** without editing your config file. Select a server in the list and toggle it — disabled servers won't start in future sessions and their tools won't be available to agents. This is useful for temporarily disabling a server that's causing slowdowns or errors without removing it from your configuration entirely. +**Toggling servers on and off**: From the `/mcp` list view, you can **enable or disable individual MCP servers** without editing your config file. Select a server in the list and toggle it — disabled servers won't start in future sessions and their tools won't be available to agents. This is useful for temporarily disabling a server that's causing slowdowns or errors without removing it from your configuration entirely. **Common causes and fixes**: