CowboyLogic/ai-dev / skills/client-config-copilotcli
client-config-copilotcli
UnverifiedManage GitHub Copilot CLI configuration files including settings.json, config.json, permissions-config.json, mcp-config.json, lsp-config.json, hooks, skills, custom agents, plugins, and custom instructions. Use this skill whenever the user wants to view, edit, add, or understand any Copilot CLI setting: trusted folders, user or repository settings, tool permissions, sandboxing, MCP or LSP servers, hooks, skills, custom agents, plugins and marketplaces, BYOK models, authentication, session management, or custom instructions. Trigger on: "add trusted folder", "allow tool", "configure MCP", "add hook", "create skill", "create agent", "install plugin", "set model", "use my own API key", "add custom instructions", "name session", "resume session", or "show my copilot config".
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 19.4 KB |
| README.md | markdown | 2.3 KB |
| SKILL.md | skill md | 7.6 KB |
| references/agents-plugins.md | markdown | 11.5 KB |
| references/cli-commands.md | markdown | 15.2 KB |
| references/config-schema.md | markdown | 37.2 KB |
| references/hooks.md | markdown | 15.6 KB |
| references/instructions.md | markdown | 4.1 KB |
| references/mcp.md | markdown | 12.1 KB |
| references/permissions.md | markdown | 22.8 KB |
| references/skills.md | markdown | 5.8 KB |
| scripts/show-config.py | script | 14.5 KB |
| scripts/update-references.py | script | 5.6 KB |
| sources.json | config | 12.2 KB |
references/config-schema.md
View on GitHub# Copilot CLI Core Configuration Reference
Covers the configuration directory, `settings.json` (user, repository, local), `config.json`,
repository model allowlists, managed settings, environment variables, authentication, BYOK
providers, and model selection.
Permissions (flags, patterns, `permissions-config.json`, sandbox) are in `permissions.md`.
CLI commands, options, and slash commands are in `cli-commands.md`.
## Configuration directory (`~/.copilot`)
Default `~/.copilot` (`$HOME/.copilot`; Windows `$HOME\.copilot`). Override the whole path with
`COPILOT_HOME`. The `--config-dir` option is deprecated — use `COPILOT_HOME`.
| Path | Type | Purpose | Edit by hand? |
|------|------|---------|---------------|
| `settings.json` | File | Personal settings (JSONC) | Yes, or `/settings` |
| `config.json` | File | App state: auth, installed plugins, `trustedFolders` | Only `trustedFolders` |
| `copilot-instructions.md` | File | Personal custom instructions | Yes |
| `instructions/` | Dir | Personal `*.instructions.md` files | Yes |
| `mcp-config.json` | File | User-level MCP servers | Yes, or `/mcp` |
| `lsp-config.json` | File | User-level LSP servers | Yes, or `/lsp` |
| `providers.json` | File | BYOK provider and model registry | Yes |
| `agents/` | Dir | Personal custom agents (`*.agent.md`) | Yes |
| `skills/` | Dir | Personal skills (`<name>/SKILL.md`) | Yes |
| `hooks/` | Dir | User-level hook files (`*.json`) | Yes |
| `extensions/` | Dir | Personal extensions | Yes |
| `permissions-config.json` | File | Saved tool/directory approvals per location | With caution |
| `installed-plugins/` | Dir | Plugin files — manage with `copilot plugin` | No |
| `plugin-data/` | Dir | Persistent plugin data | No |
| `session-state/` | Dir | Session history (`events.jsonl`) — enables `--resume`/`--continue` | No |
| `command-history-state/` | Dir | Prompt history for `Ctrl+R` | No |
| `session-store.db` | File | SQLite cross-session index (rebuild with `/chronicle reindex`) | No |
| `logs/` | Dir | `process-{timestamp}-{pid}.log` per session — safe to delete | No |
| `ide/` | Dir | IDE integration lock files | No |
| `mcp-oauth-config/` | Dir | MCP OAuth fallback storage when no keychain | No |
| `mcp-secrets/` | Dir | MCP secret placeholder fallback storage | No |
Items are created on demand (for example, `installed-plugins/` appears after the first install).
The cache directory is **not** affected by `COPILOT_HOME`: macOS `~/Library/Caches/copilot`,
Linux `$XDG_CACHE_HOME/copilot` or `~/.cache/copilot`, Windows `%LOCALAPPDATA%/copilot`.
Override with `COPILOT_CACHE_HOME`.
Run `copilot help config` for a quick terminal reference.
---
## Settings precedence
Later overrides earlier:
1. Built-in defaults
2. MDM managed settings
3. User settings — `~/.copilot/settings.json`
4. Repository settings — `.github/copilot/settings.json` (committed)
5. Local settings — `.github/copilot/settings.local.json` (add to `.gitignore`)
6. Environment variables
7. Command-line flags
Exceptions: an MDM `permissions.disableBypassPermissionsMode` of `"disable"` always wins, and
managed `sandbox` values set a floor users cannot relax.
The CLI also reads `.claude/settings.json` and `.claude/settings.local.json` in the repository for
the shared cross-tool subset (such as `companyAnnouncements`, `disableAllHooks`,
`enabledPlugins`, `extraKnownMarketplaces`, and `hooks`).
---
## settings.json (user)
**Location**: `~/.copilot/settings.json` (or `$COPILOT_HOME/settings.json`). JSON with comments
(JSONC) is supported.
- Edit directly, or use `/settings` (alias `/config`) in a session: `/settings KEY VALUE`,
`/settings show KEY`, `/settings KEY` (shows valid values). Nested keys use dots:
`/settings footer.showBranch off`. Booleans accept `on`/`off` or `true`/`false`.
- List/structured settings and security-sensitive settings can't be set inline — press
`Ctrl+E` in the `/settings` editor to open the file.
- Invalid values or unknown top-level keys are ignored and listed in the **Problems** tab of
`/settings`. `$schema` is tolerated.
- User settings used to live in `config.json`. Settings left there are **ignored** — `config.json`
now holds only internal state such as installed plugins and trusted folders.
- If `settings.json` is a symlink (dotfiles), `/settings` writes follow the symlink.
- A few settings (for example, `experimental` and proxy settings) need a restart.
```json
{
"model": "auto",
"effortLevel": "medium",
"theme": "dim",
"autoUpdate": true,
"continueOnAutoMode": true,
"allowedUrls": ["*.github.com"],
"disabledSkills": ["legacy-skill"],
"footer": { "showBranch": true }
}
```
### User setting keys
| Key | Type / values | Default | Purpose |
|-----|---------------|---------|---------|
| `allowedUrls` | `string[]` | `[]` | URLs/domains allowed without prompting; supports `*.github.com` |
| `askUser` | boolean | `true` | Allow clarifying questions (`--no-ask-user` disables) |
| `assistedApprovalInstructions` | not documented | not documented | **v1.0.101 release notes only:** guides Assisted Permissions confirmation decisions. The settings reference doesn't list it, so its value type is unverified |
| `autoTier` | `"efficiency"` \| `"balance"` \| `"intelligence"` | unset | Default Auto routing tier when `model` is `auto` (see `/model auto TIER`); `"fast"` is no longer selectable and falls back to `"balance"` |
| `autoUpdate` | boolean | `true` | Auto-download CLI updates and update first-party plugins |
| `autoUpdatesChannel` | `"stable"` \| `"prerelease"` | `"stable"` | Update channel |
| `banner` | `"always"` \| `"once"` \| `"never"` | `"once"` | Startup banner frequency |
| `bashEnv` | boolean | `false` | `BASH_ENV` support |
| `beep` / `beepOnSchedule` | boolean | `true` | Audible beep on attention / scheduled run finished |
| `colorMode` | theme values | `"github"` | **Deprecated** alias for `theme` |
| `commandHistoryMaxSize` | number (1–1000) | `50` | Retained prompt history |
| `compactPaste` | boolean | `true` | Collapse pastes over 10 lines |
| `companyAnnouncements` | `string[]` | `[]` | Random startup messages |
| `connectors` | boolean | `true` | Enable Copilot Connectors when available |
| `continueOnAutoMode` | boolean | `false` | Switch to auto mode on eligible rate limits (not global limits or BYOK) |
| `copyOnSelect` | boolean | `true` macOS, else `false` | Copy mouse selection to clipboard |
| `customAgents.defaultLocalOnly` | boolean | `false` | Only local custom agents (no org/enterprise agents) |
| `defaultPermissionMode` | `"manual"` \| `"assisted"` \| `"allow-all"` | varies | Permission mode for new **interactive** sessions; a managed `permissions.defaultMode` wins; deny rules and enterprise restrictions still apply; resumed sessions keep their own mode; not applied to non-interactive runs or remote sessions; an unavailable or blocked mode falls back to manual approval |
| `deniedUrls` | `string[]` | `[]` | Always-denied URLs; deny beats allow |
| `disableAllHooks` | boolean | `false` | Disable repository and user hooks |
| `disabledMcpServers` | `string[]` | `[]` | Configured but not started |
| `disabledSkills` | `string[]` | `[]` | Discovered but not loaded |
| `dynamicRetrieval` | `{ skills?: boolean }` | unset | `skills: false` disables embeddings retrieval for skills |
| `editorMode` | `"normal"` \| `"vim"` | `"normal"` | Composer mode (`/vim` toggles) |
| `effortLevel` | `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` | `"medium"` | Reasoning effort |
| `enabledMcpServers` | `string[]` | `[]` | Enable built-in MCP servers that are off by default |
| `enabledPlugins` | `Record<string, boolean>` | `{}` | Declarative plugin auto-install |
| `experimental` | boolean | `false` | Experimental features (`--experimental`, `/experimental`) |
| `extraKnownMarketplaces` | `Record<string, {...}>` | `{}` | Extra plugin marketplaces; `source` required (`"directory"`, `"git"`, `"github"`); optional `autoUpdate: true` |
| `footer` | object | — | Status-line items: `showModelEffort`, `showDirectory`, `showBranch`, `showContextWindow`, `showQuota`, `showAgent`, `showAiUsed`, `showCodeChanges`, `showUsername`, `showSandbox`, `showYolo`, `showCustom` (managed by `/statusline`) |
| `hooks` | object | — | Inline hooks keyed by event (same schema as hook files) |
| `ide.autoConnect` / `ide.openDiffOnEdit` | boolean | `true` | IDE auto-connect / show edit diffs in IDE |
| `ignoredSkillsLocations` | `string[]` | `[]` | Skill directories (and descendants) excluded from discovery; `~`-relative paths supported |
| `includeCoAuthoredBy` | boolean | `true` | `Co-authored-by` trailer on agent commits |
| `inlineImages` | boolean | `true` | Render images inline with the Kitty graphics protocol (Ghostty, kitty, or WezTerm); otherwise image attachments show a text placeholder. v1.0.97 release notes: renders by default on supported terminals without experimental mode; turn off with `/settings inlineImages false` |
| `keepAlive` | `"on"` \| `"off"` \| `"busy"` | `"off"` | Prevent system sleep |
| `logLevel` | `"none"` \| `"error"` \| `"warning"` \| `"info"` \| `"debug"` \| `"all"` \| `"default"` | `"default"` | Log verbosity |
| `mergeStrategy` | `"rebase"` \| `"merge"` | — | Strategy for `/pr fix conflicts` |
| `model` | string | varies | Default model; `"auto"` lets Copilot choose |
| `mouse` | boolean | `true` | Mouse support |
| `permissions.disableBypassPermissionsMode` | `"disable"` \| `"allow-auto-only"` | — | Block allow-all flags (see `permissions.md`) |
| `pinnedPrompts` | boolean | `true` | Pin current prompt while scrolling |
| `powershellFlags` | `string[]` | `["-NoProfile", "-NoLogo"]` | Windows only |
| `proxyUrl` / `proxyKerberosServicePrincipal` | string | unset | HTTP(S) proxy; `HTTP_PROXY`/`HTTPS_PROXY` override |
| `remoteSessions` | boolean | `false` | Enable remote control by default for interactive sessions when it is available; `/remote on`/`/remote off` change it per session. Separate from `remoteExport`. The settings reference no longer lists the old `remote` (`"on"`/`"off"`) key |
| `remoteExport` | boolean | `true` | Sync session history to your account when sync is available. `remoteSessions: true` also enables export. Syncing alone does not enable remote control; `--sync-session=on\|off` overrides it for one run |
| `renderHexColors` / `renderMarkdown` | boolean | `true` | Terminal rendering |
| `respectGitignore` | boolean | `true` | Hide gitignored files from `@` picker |
| `sandbox.*` | object | — | Local sandbox: `enabled`, `allowBypass`, `auth.git`, `auth.gh`, `credentials.envVars`, `userPolicy.*` (see `permissions.md`) |
| `screenReader` | boolean | `false` | Screen reader optimizations |
| `scrollbar` | boolean | `true` | Scrollbar in scrollable views |
| `shellShortcut` | boolean | `true` | Lone `$` + `Enter` opens a shell (user/managed scope only) |
| `showReasoning` | boolean | unset | Show model reasoning in the timeline; set with `/config` or `/settings`, or toggle with `Ctrl+T`. Saved across sessions |
| `showTimestamps` / `showTipsOnStartup` | boolean | `true` | UI toggles |
| `sidebar` | boolean | `true` | Current-session sidebar |
| `skillDirectories` | `string[]` | `[]` | Extra skill search directories |
| `statusLine` | object | — | Custom status line: `type: "command"`, `command`, optional `padding`, `refreshInterval` (seconds) |
| `stayInAutopilot` | boolean | `true` | Stay in autopilot after a task completes |
| `storeTokenPlaintext` | boolean | `false` | Allow plaintext token in `config.json` when no keychain |
| `stream` | boolean | `true` | Streaming responses |
| `streamerMode` | boolean | `false` | Hide model names, quota, timestamps for screen sharing |
| `subagents.agents` | object | `{}` | Per-agent `model`, `modelPolicy`, `effortLevel`, `contextTier` (see `agents-plugins.md`) |
| `subagents.agents["rubber-duck"].autoInvoke` | boolean | `false` | Let Copilot consult the rubber-duck agent proactively (toggle in `/subagents` → **Proactive invocation**) |
| `subagents.disabledSubagents` | `string[]` | `[]` | Names of subagents that are turned off (manage with `/subagents`) |
| `subagents.maxConcurrency` / `subagents.maxDepth` | number | plan-based / `6` | Usage-based billing only; capped at `32` / `256` |
| `tabs.enabled` / `tabs.hide` / `tabs.sort` | boolean / `string[]` | `true` / `[]` / `[]` | Home tab bar (`copilot`, `agents`, `issues`, `pull-requests`, `gists`) |
| `taskbarPresence` | boolean | `true` | Windows taskbar presence |
| `terminalNotifications` | boolean | `false` | Prefer terminal-owned OSC 777 notifications (Ghostty, WezTerm) when desktop notifications are enabled |
| `terminalProgress` | boolean | `true` | OSC 9;4 progress indicators |
| `theme` | `"default"` \| `"github"` \| `"dim"` \| `"high-contrast"` \| `"colorblind"` | `"github"` | Color palette |
| `toolSearch` | boolean | model-dependent | `false` opts out of deferred tool loading |
| `transcriptView` | `"default"` \| `"concise"` | `"default"` | Timeline grouping |
| `updateTerminalTitle` | boolean | `true` | Show intent in terminal title |
| `worktreeBaseRef` | `"head"` \| `"defaultBranch"` | `"head"` | Base for `/worktree` and `--worktree` |
| `worktreePathTemplate` | string | unset | Where worktrees are created, e.g. `~/src/worktrees/{repo}/{branch}`; placeholders `{repoPath}`, `{repo}`, `{branch}`, `{branchSlug}`. Default layout is `<repo>.worktrees/` |
`trustedFolders` is **not** a `settings.json` key — it lives in `config.json`.
---
## Repository and local settings
**Repository**: `.github/copilot/settings.json` (committed). **Local**:
`.github/copilot/settings.local.json` (gitignored; same schema, overrides repository).
Only these keys are honored at repository/local level — anything else is silently ignored:
| Key | Merge behavior |
|-----|----------------|
| `companyAnnouncements` | Replaced — repository wins |
| `contextTier` (`"default"` \| `"long_context"`) | Replaced — repository wins |
| `deniedUrls` | Union — repository can add, never remove |
| `disableAllHooks` | Repository wins |
| `disabledMcpServers` | Union |
| `disabledSkills` | Union |
| `effortLevel` | Replaced — repository wins |
| `enabledPlugins` | Merged — repository overrides same key |
| `extraKnownMarketplaces` | Merged — repository overrides same key (`autoUpdate` accepted but ignored) |
| `hooks` | Merged — repository overrides same key |
| `includeCoAuthoredBy` | Replaced — repository wins |
| `mergeStrategy` | Replaced — repository wins |
| `model` | Replaced — repository wins |
| `respectGitignore` | Tighten-only — repository can enable, never disable |
- `model`, `effortLevel`, and `contextTier` overrides only apply when the directory is trusted.
- A plugin enabled only via repository `enabledPlugins` is scoped to that repository.
- Repository `enabledPlugins` and `extraKnownMarketplaces` are also read by Copilot cloud agent.
- Set repo values in-session with `/settings --repo KEY VALUE` or `/settings --local KEY VALUE`.
### Repository model allowlist (`.github/allowed_models.txt`)
Plain text, one rule per line, resolved from the repository root:
```text
# .github/allowed_models.txt
fallback: gpt-6-astra
gpt-6-astra
gpt-5.4
claude-sonnet-*
```
- Lines are exact model IDs or globs; `#` starts a comment; `*` allows all (the default with no file).
- `fallback: MODEL-ID` is required exactly once, must be an exact ID, and must match an allowed rule.
- Negated patterns (`!pattern`) aren't supported. Re-evaluated on `/cd`.
- Governs built-in models only — BYOK models are never filtered.
---
## config.json
**Location**: `~/.copilot/config.json` (or `$COPILOT_HOME/config.json`). Automatically managed
application state (auth data, installed plugin metadata, `loggedInUsers`, `installedPlugins`,
`firstLaunchAt`, `staff`). Put user preferences in `settings.json`, not here. (v1.0.97 release
notes: one invalid entry in `config.json` no longer resets the saved settings, such as dismissed
prompts, trusted folders, and sign-ins, on every launch.)
### trustedFolders (array)
The one field you edit by hand. Controls where Copilot can read, modify, and execute files.
```json
{
"trustedFolders": [
"/home/user/projects/my-app",
"C:\\Users\\user\\projects"
]
}
```
- At startup you're asked to trust the launch directory for this session only, or for this and
future sessions (the latter writes to `trustedFolders`).
- Scoping is heuristic — GitHub does not guarantee files outside trusted directories are protected.
Only trust directories whose contents you control.
- Trust gates project-level MCP servers, hooks, skills, and plugins, plus repository `model`,
`effortLevel`, and `contextTier` overrides.
---
## Managed settings (administrators)
Loaded at startup as a policy baseline; server-managed settings fill keys MDM leaves unset.
Long-running sessions re-apply managed settings hourly.
| Platform | Source |
|----------|--------|
| macOS | MDM plist `com.github.copilot`, or `/Library/Application Support/GitHubCopilot/managed-settings.json` |
| Windows | Registry `HKLM\SOFTWARE\Policies\GitHubCopilot`, or `%ProgramFiles%\GitHubCopilot\managed-settings.json` |
| Linux | `/etc/github-copilot/managed-settings.json` |
On POSIX, file-based managed settings are rejected if they are symlinks, not owned by root, or
world-writable.
Supported keys: `allowedMcpServers`, `autoTier`, `deniedMcpServers`, `enabledPlugins`,
`extraKnownMarketplaces`, `forceLoginOrgs`, `forceRemoteSettingsRefresh`, `fusionTier`, `model`, `permissions`
(including `disableAssistedPermissionsMode`, `defaultMode`, `disableBypassPermissionsMode`, `deny`/`ask`/`allow` rules, and `limitTo`),
`policyHelper`, `remoteControl`, `requireBase64ImageAttachments`, `sandbox`, `shellShortcut`,
`strictKnownMarketplaces`, `telemetry`. See `permissions.md` for managed permission rules and `mcp.md` for the MCP
allow/deny list.
- `model` is a top-level key; the legacy nested `permissions.model` still works as a fallback.
Besides a model ID or `"auto"`, it accepts `"fusion"` (Copilot Fusion) as the default.
- `fusionTier` sets the default effort level when `model` is `"fusion"`: `"standard"`, `"high"`, `"max"`, or
`"unmanaged"` (most to least restrictive). A bare string other than `"unmanaged"` locks the level;
`{"overridable": "standard"}` sets a default that teams may override. It does not select the model.
Requires Copilot CLI 1.0.104-3 or later (VS Code 1.144.0, GitHub Copilot app 1.1.33-4).
The v1.0.104 release notes add that a managed `fusion` model starts sessions on Auto and applies
`fusionTier` (release notes only).
- `permissions.disableAssistedPermissionsMode: true` stops users enabling assisted permissions and does
not disable bypass mode. `permissions.defaultMode` (`"manual"`, `"assisted"`, `"allow-all"`) is a
managed default, not a lock; an explicit permitted choice for a session wins, and it takes precedence
over the user's `defaultPermissionMode`.
- `autoTier` as a bare string locks the tier; `{"overridable": "TIER"}` sets an organization
default users and repositories may still override.
- `policyHelper` registrations are validated, but the docs say the runtime doesn't yet invoke the
helper.
- `sandbox` sets a policy floor users can't relax. Supported fields: `enabled`,
`failIfUnavailable`, `allowBypass`, `addCurrentWorkingDirectory`, `sandboxMcpServers`,
`sandboxLspServers`, `auth.git`, `auth.gh`, `allowDevToolAccess`, `learningMode`, and the
`userPolicy.*` filesystem and network rules. The managed value wins in the safer direction;
sandboxing, `failIfUnavailable`, and sandboxed MCP/LSP servers can't be turned off. `learningMode`
is Windows-only and honored only from native MDM (a `managed-settings.json` value is ignored).
The managed `sandbox` key blocks connections from clients older than the minimum version that
supports local sandbox: Copilot CLI 1.0.93, VS Code 1.141.0, GitHub Copilot app 1.1.26
(enterprise managed settings reference).
- `forceRemoteSettingsRefresh: true` requires a fresh server-managed settings download at startup
(Copilot CLI, VS Code, and the GitHub Copilot app). In the CLI and the app it skips the one-hour
cache and doesn't fall back to an older cached policy: if the fetch fails, affected operations
stay restricted until current policy is confirmed. In VS Code, Copilot features are blocked until
the refresh succeeds. The MDM value takes precedence over a cached server value. To apply from a
device's first startup, deliver it through MDM or file-based settings; policy helper scripts
can't set it. In the Windows registry or macOS managed preferences, store it as a string
`true`/`false`, not a DWORD or native Boolean.
- `requireBase64ImageAttachments: true` requires base64-encoded image attachments instead of
attachment URLs; `false` or unset keeps the existing behavior.
- `telemetry` pushes baseline OpenTelemetry export settings: `enabled`, `endpoint`, `protocol`,
`headers`, `headersProvider` (a command that supplies fresh OTLP headers, or `false`; see
[Dynamic authentication headers](#dynamic-authentication-headers)), `resourceAttributes`,
`serviceName`, and the capture controls below (see
[OpenTelemetry monitoring](#opentelemetry-monitoring)). `capture` is an object of independent
switches, each defaulting to `false`: `identity` (account name as `user.name`, OS account as
`process.user.name`, machine as `host.name`), `prompts` (prompt text and model input,
including attachments, compaction summaries, skill content, and workspace context), `responses`
(assistant text and reasoning), `toolArguments` (raw arguments, commands, denied resources,
tool descriptions and schemas, and raw MCP server, plugin, hook, and tool identifiers),
`toolOutput` (tool, hook, MCP server, and subagent results and error details), and
`policyDetail` (unbounded policy details such as raw sandbox path arrays; bounded posture and
counts stay available). `captureContent` is the legacy shorthand that toggles
all five content classes together and does not affect `identity`; an explicitly set `capture`
field wins over it for that class.
`lockCaptureContent: true` stops local settings from enabling a legacy content class unless the
managed object configures that class or `captureContent`, and it does not govern `identity`.
Setting only `capture.identity` attributes traces to a user and machine without collecting
content. Fine-grained controls apply in Copilot CLI, the GitHub Copilot app, and VS Code sessions
using Agent Host; VS Code's local agent harness honors only `capture.identity` and
`captureContent`.
- `remoteControl.mode` is `"enabled"`, `"disabled"`, or `"requireSSO"`; `requireSSO` needs
`remoteControl.githubDotComOrganizations`, and the client must be SSO-authorized for at least one
listed organization.
- Most managed keys lock the whole row. `enabledPlugins` and `extraKnownMarketplaces` are the
exception: the managed layer merges those maps field by field with the user's entries.
---
## Environment variables
| Variable | Purpose |
|----------|---------|
| `COPILOT_HOME` | Config/state directory (default `$HOME/.copilot`) |
| `COPILOT_CACHE_HOME` | Cache directory override |
| `COPILOT_ALLOW_ALL` | Truthy (`true`, `1`, `yes`, `on`, `y`) = `--allow-all`. Exactly `true` also trusts the working directory (loads its skills, plugins, MCP servers, and hooks) |
| `COPILOT_AUTO_UPDATE` | `false` disables CLI and first-party plugin auto-updates |
| `COPILOT_MODEL` | Model to use |
| `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | Auth tokens, in that precedence order |
| `COPILOT_GH_HOST` | GitHub hostname for Copilot CLI only; overrides `GH_HOST` |
| `GH_HOST` | GitHub hostname for `gh` and Copilot CLI (default `github.com`) |
| `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Extra instruction directories (comma-separated) |
| `COPILOT_SKILLS_DIRS` | Extra skill directories (comma-separated) |
| `COPILOT_EDITOR` | Editor (checked after `$VISUAL` and `$EDITOR`; default `vi`) |
| `COPILOT_MCP_TOOL_CACHE` | `false` disables MCP tool snapshot caching |
| `COPILOT_LARGE_OUTPUT_THRESHOLD_BYTES` | Max tool output returned directly to the model (default `20480`) |
| `COPILOT_PLAN_THEN_AUTOPILOT` | Truthy = `--plan --mode autopilot` |
| `COPILOT_SUBAGENT_MAX_CONCURRENT` / `COPILOT_SUBAGENT_MAX_DEPTH` | Subagent limits (defaults `32` / `4` per this table; see note) |
| `COPILOT_TASK_WAIT_TIMEOUT_SECONDS` | Max seconds `-p` and `-p --autopilot` wait for pending background agents or shell commands before exiting (default `600`; `0` exits immediately). **v1.0.104 release notes only:** interactive and SDK Autopilot sessions keep waiting for attached background tasks instead of stopping at this timeout |
| `COPILOT_ASSISTED_APPROVAL` | `true` turns on assisted permissions for a non-interactive run (same as `--assisted-approval`) |
| `COPILOT_ENABLE_HTTP2` | `1`/`true` opts into HTTP/2 |
| `COPILOT_ENABLE_INTERRUPTED_SESSION_RESTORE` | `1` enables restoring crashed sessions |
| `COPILOT_PROMPT_FRAME` | `1`/`0` toggles the prompt frame |
| `COPILOT_STRIP_REASONING_ON_RESUME` | `0`/`false` keeps BYOK reasoning tokens on resume |
| `COPILOT_CHILD_OOM_SCORE_ADJ` | Linux OOM bias for child processes (default `300`; `off` disables) |
| `COPILOT_WEB_FETCH_ALLOW_LOCALHOST` | `1` lets `web_fetch` reach `localhost` |
| `COPILOT_HOOK_ALLOW_LOCALHOST` | `1` allows `http://localhost` HTTP hooks |
| `COPILOT_OFFLINE` | `true` = no GitHub contact, no telemetry (BYOK only) |
| `COPILOT_PROVIDER_*` / `COPILOT_PROVIDERS_CONFIG` | BYOK (see below) |
| `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` | `true` loads workspace MCP servers in `-p` in untrusted dirs |
| `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS` | `true` loads repository hooks in `-p` |
| `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS` | `true` loads project extensions in `-p` |
| `PLUGINS_DASHBOARD` | `false` disables the plugins dashboard and `copilot plugin` commands |
| `PLAIN_DIFF` | `true` disables rich diffs |
| `USE_BUILTIN_RIPGREP` | `false` uses system ripgrep |
| `USE_TGREP` | `true`/`false` forces tgrep / ripgrep |
| `TGREP_FILE_COUNT_THRESHOLD` | Minimum file count for automatic tgrep search (default `10000` on Windows, `50000` elsewhere) |
> [!NOTE]
> The upstream docs disagree on subagent defaults: the environment-variable table lists
> `COPILOT_SUBAGENT_MAX_DEPTH` default `4` (range 1–128) and max concurrent `32` (range 1–256),
> while the subagent-limits table and `subagents.*` settings list depth default `6` (cap `256`)
> and plan-based concurrency (cap `32`). Treat the settings values as authoritative for
> `settings.json`.
---
## OpenTelemetry monitoring
Copilot CLI can export OpenTelemetry traces and metrics that follow the OTel GenAI semantic
conventions. Export is off by default and turns on when `COPILOT_OTEL_ENABLED=true`,
`OTEL_EXPORTER_OTLP_ENDPOINT` is set, or `COPILOT_OTEL_FILE_EXPORTER_PATH` is set. Enterprise
administrators can push a baseline through the managed `telemetry` key.
| Variable | Default | Purpose |
|----------|---------|---------|
| `COPILOT_OTEL_ENABLED` | `false` | Explicitly enable export (not needed when an endpoint is set) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP endpoint URL; setting it enables export |
| `COPILOT_OTEL_EXPORTER_TYPE` | `otlp-http` | `otlp-http` or `file`; `file` is chosen automatically when `COPILOT_OTEL_FILE_EXPORTER_PATH` is set |
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | — | Write all signals to this file as JSON lines; setting it enables export |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/json` | `http/json` or `http/protobuf` (`otlp-http` only); `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` / `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` override it per signal |
| `OTEL_EXPORTER_OTLP_HEADERS` | — | Auth headers for the exporter |
| `OTEL_SERVICE_NAME` | `github-copilot` | `service.name` resource attribute |
| `OTEL_RESOURCE_ATTRIBUTES` | — | Extra resource attributes, comma-separated `key=value` (percent-encode special characters) |
| `COPILOT_OTEL_SOURCE_NAME` | `github.copilot` | Instrumentation scope name for the tracer and meter |
| `OTEL_LOG_LEVEL` | — | Diagnostic level: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`, `ALL` |
| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | Capture full prompts, responses, tool schemas, and tool arguments and results |
### Dynamic authentication headers
Set `telemetry.headersProvider` in user settings or in a managed telemetry policy to run a command
that supplies fresh OTLP headers. Repository settings never apply it; `false` disables it.
```json
{
"telemetry": {
"headersProvider": {
"path": "node",
"args": ["bin/otel-headers.js"],
"refreshIntervalMs": 1740000
}
}
}
```
- `path` is an executable name, absolute path, or home-relative path, not a shell command;
workspace-relative paths are rejected. `args` are passed literally, so name an interpreter for
scripts. `refreshIntervalMs` defaults to 29 minutes.
- The command runs from your home directory with a 30-second deadline and must print a JSON object
of string header values to stdout; an empty object clears dynamic headers.
- It runs only for active HTTP OTLP exporters. Use HTTPS: an HTTP endpoint produces a warning and
OTLP redirects are rejected.
- Precedence, highest first: managed helper output, managed static headers, user helper output,
then `OTEL_EXPORTER_OTLP_HEADERS`. A managed `false` disables helpers.
- If a refresh fails, exports that need dynamic headers are blocked until the next refresh.
### Signals
- **Traces:** an `invoke_agent` root span per agent invocation, with `chat` (one per LLM request)
and `execute_tool` child spans. Subagent invocations also use `invoke_agent` spans.
- **Metrics:** `gen_ai.client.operation.duration`, `gen_ai.client.token.usage`,
`gen_ai.client.operation.time_to_first_chunk`, `gen_ai.client.operation.time_per_output_chunk`,
`gen_ai.invoke_agent.duration`, `gen_ai.invoke_agent.inference_calls`,
`gen_ai.invoke_agent.tool_calls`, `gen_ai.invoke_workflow.duration`, plus
`github.copilot.tool.call.count`, `github.copilot.tool.call.duration`,
`github.copilot.agent.turn.count`, `github.copilot.mcp.server.connection.count`,
`github.copilot.code.lines_added`, and `github.copilot.code.lines_removed`.
- **Span events** on `chat` / `invoke_agent` spans: `github.copilot.hook.start`,
`github.copilot.hook.end`, `github.copilot.hook.error`, `github.copilot.session.truncation`,
`github.copilot.session.compaction_start`, `github.copilot.session.compaction_complete`,
`github.copilot.skill.invoked`, `github.copilot.session.shutdown`, `github.copilot.session.abort`,
and `exception`.
> [!WARNING]
> By default only metadata (model names, token counts, durations) is captured. Content capture can
> include code, file contents, and prompts; enable it only in trusted environments.
To measure AI-unit consumption, read `github.copilot.nano_aiu` from the root `invoke_agent` span
only: it is also stamped on child `chat` spans, so summing across spans double-counts.
`github.copilot.cost` is a per-request model multiplier used for billing, not a monetary value. The
full catalog is in the
[command reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#opentelemetry-monitoring).
---
## Auth
### Credential resolution order
1. `COPILOT_GITHUB_TOKEN`
2. `GH_TOKEN`
3. `GITHUB_TOKEN`
4. OAuth token from the system keychain
5. GitHub CLI fallback (`gh auth token`)
An environment variable silently overrides a stored OAuth token. Exception: in Codespaces the
auto-injected `GITHUB_TOKEN` does not beat an account signed in with `/login`.
### Supported token types
| Type | Prefix | Supported |
|------|--------|-----------|
| OAuth token (browser or device flow) | `gho_` | Yes |
| Fine-grained PAT | `github_pat_` | Yes — user-owned, with **Copilot Requests** account permission |
| GitHub App user-to-server | `ghu_` | Yes (env var only) |
| Classic PAT | `ghp_` | No |
### Credential storage
Keychain service name `copilot-cli`: macOS Keychain Access, Windows Credential Manager, Linux
libsecret (GNOME Keyring / KWallet). With no keychain, the CLI prompts to store the token in
plaintext in `~/.copilot/config.json` (`storeTokenPlaintext` setting).
### Auth commands
```bash
copilot login # browser flow locally, device code when remote/CI
copilot login --host https://example.ghe.com # GHE Cloud with data residency
copilot login --device-code # force device code flow
copilot login --web-flow # force browser flow
copilot login --with-token < token.txt # read token from stdin
```
In a session: `/login`, `/logout` (removes local token, doesn't revoke), `/user list`,
`/user switch`, `/user show`.
---
## BYOK (Bring Your Own Key)
Use your own provider instead of GitHub-hosted models. GitHub auth becomes optional, but without
it `/delegate`, the GitHub MCP server, and GitHub code search are unavailable. Run
`copilot help providers` for more examples.
Models must support **tool calling** and **streaming**; 128k+ context recommended.
### BYOK environment variables
| Variable | Required | Description |
|----------|----------|-------------|
| `COPILOT_PROVIDER_BASE_URL` | Yes | API endpoint base URL |
| `COPILOT_MODEL` | Yes | Model identifier (or `--model`) |
| `COPILOT_PROVIDER_TYPE` | No | `openai` (default) \| `azure` \| `anthropic` |
| `COPILOT_PROVIDER_API_KEY` | No | API key (not needed for local Ollama) |
| `COPILOT_PROVIDER_API_KEY_COMMAND` | No | Command printing a fresh key before each request; beats `COPILOT_PROVIDER_API_KEY` |
| `COPILOT_PROVIDER_BEARER_TOKEN` | No | Bearer token when not using an API key |
| `COPILOT_PROVIDER_HEADERS` | No | Custom headers (referenced by the docs; format not documented) |
| `COPILOT_PROVIDER_WIRE_API` | No | API protocol used with the provider |
| `COPILOT_PROVIDER_AZURE_API_VERSION` | Azure | Azure OpenAI API version |
| `COPILOT_PROVIDER_MODEL_ID` | No | Well-known model name (capabilities, token limits) |
| `COPILOT_PROVIDER_WIRE_MODEL` | No | Model name sent to the API (Azure: deployment name) |
| `COPILOT_PROVIDER_MAX_PROMPT_TOKENS` | No | Max prompt tokens per request |
| `COPILOT_PROVIDER_MAX_OUTPUT_TOKENS` | No | Max output tokens |
| `COPILOT_OFFLINE` | No | `true` = no GitHub contact or telemetry; only air-gapped if the provider is local |
### providers.json
`~/.copilot/providers.json` (override with `COPILOT_PROVIDERS_CONFIG`) is a JSON object with
`providers` and `models` keys. When it declares any provider or model it takes precedence over the
`COPILOT_PROVIDER_*` variables. The upstream docs don't publish the entry schema — run
`copilot help providers` before writing one.
### Provider examples
#### Ollama (local, no key)
```bash
export COPILOT_PROVIDER_BASE_URL=http://localhost:11434
export COPILOT_MODEL=llama3.2
```
#### OpenAI
```bash
export COPILOT_PROVIDER_BASE_URL=https://api.openai.com/v1
export COPILOT_PROVIDER_API_KEY=YOUR-OPENAI-API-KEY
export COPILOT_MODEL=gpt-4o
```
#### Azure OpenAI
```bash
export COPILOT_PROVIDER_BASE_URL=https://YOUR-RESOURCE-NAME.openai.azure.com
export COPILOT_PROVIDER_TYPE=azure
export COPILOT_PROVIDER_API_KEY=YOUR-AZURE-API-KEY
export COPILOT_PROVIDER_AZURE_API_VERSION=YOUR-AZURE-API-VERSION
export COPILOT_PROVIDER_MODEL_ID=YOUR-MODEL-NAME
export COPILOT_PROVIDER_WIRE_MODEL=YOUR-DEPLOYMENT-NAME
export COPILOT_MODEL=YOUR-DEPLOYMENT-NAME
```
#### Anthropic
```bash
export COPILOT_PROVIDER_TYPE=anthropic
export COPILOT_PROVIDER_BASE_URL=https://api.anthropic.com
export COPILOT_PROVIDER_API_KEY=YOUR-ANTHROPIC-API-KEY
export COPILOT_MODEL=YOUR-MODEL-NAME
```
---
## Model usage
- Select with `/model` (alias `/models`), `--model=MODEL`, `COPILOT_MODEL`, or the `model` setting.
`auto` lets Copilot choose.
Model IDs are case-insensitive and the canonical ID is saved (`/model` and `/config model`).
- `/model` scope flags: `--session`/`-s` (default, current session only), `--global` (saved default),
`--repo`/`--local` (pins in repository settings).
- Reasoning effort: `--effort`/`--reasoning-effort` (`low`, `medium`, `high`, `xhigh`, `max`;
`max` is Anthropic-only) or the `effortLevel` setting.
- Context tier: `--context default|long_context`. Latest models offer a 1M-token extended context
and configurable reasoning; both consume more AI credits, so default to regular settings.
- Copilot Fusion: selecting `fusion` (or **Copilot Fusion** in `/model`) picks a model or execution
pattern automatically; its effort level is Standard, High, or Max. v1.0.105 release notes: choosing
Fusion High or Max now works from long-context sessions (release notes only). When a saved Auto
preference is no longer available, Auto falls back to its default instead of failing each turn
(v1.0.104 release notes only).
- Local models (public preview, needs `--experimental` or `/experimental on`): on a Windows PC with an
NVIDIA GPU (not AMD), `/model` lists MAI Code 1.1 Flash (96 GB combined RAM, 60 GB storage) and Flint
NVFP4 (48 GB, 23 GB) under "Local and self-hosted" as "Download required". They need llama.cpp
(build b11669 or later for MAI Code, b11803 or later for Flint) with `LLAMACPP_SERVER_PATH` pointing
to `llama-server.exe`. Only MAI Code 1.1 Flash is used by Fusion Standard. Do not load the same local
model from several Copilot surfaces at once (each loads its own copy into memory). Local models can
also be assigned to a custom agent.
- Auto routing tier: `autoTier` setting or `/model auto TIER` (`efficiency`, `balance`,
`intelligence`).
- The supported-model roster changes often and retired models stop resolving; check the
[supported models](https://docs.github.com/en/copilot/reference/ai-models/supported-models)
page (including its retirement table) before pinning a model ID.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |