|
|
|
@@ -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 `<repo>.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 `<repo>.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 <directory>` 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 <directory>` 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 <TAB>` 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 <TAB>` 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
|
|
|
|
|
|
|
|
|
|
github-actions[bot]