Guides for GitHub Copilot CLI

GitHub Copilot CLI is GitHub's coding agent for the terminal. You give it a task in plain language and it reads files, runs commands, edits code, and reports back, asking for approval according to your permission settings. It also runs in prompt mode with copilot -p for scripts and CI. A fact that is true in an interactive session is not always true in prompt mode, so the guides here say which surface they mean.

Each Copilot CLI guide starts from one symptom in an interactive session or in prompt mode and traces it back to the instruction, skill, permission or hook that produced it. The order runs from what the agent was told, to what it can load on demand, to what it remembers, and to what it is allowed to do.

Run copilot --version before you use a page. The changelog moves weekly: 1.0.104 on 27 October 2026.

Checked against GitHub's Copilot CLI documentation on 27 October 2026.

Start with the problem#

Why Copilot CLI ignores your AGENTS.md or instructions — Which files load, how they are combined, and why there is no general precedence order to appeal to. It also shows the checks that work: /instructions, /env, and copilot instruction list.

Why your Copilot CLI skill isn't being used — A skill can be listed in /skills and still never trigger. The description is the trigger, the injected list has a budget, and explicit invocation is a different path from automatic selection.

Custom agents in Copilot CLI — Why /agent does not show your .agent.md, what a subagent inherits from the repository, and what it does not.

Where did my Copilot CLI session go? — Sessions live under ~/.copilot/session-state/, and the picker is not the whole library. Finding, resuming, forking, and recovering a session that seems lost.

Why Copilot CLI keeps asking for permission — Allow and deny rules, saved approvals, the sandbox, and why denying read can block more than you intended.

Why your Copilot CLI hook or plugin isn't firing — Where hooks load, which events exist, and how to tell "not loaded" from "loaded but the command failed".

Also in this set#

• Context compaction: what your coding agent drops — the Copilot CLI section covers /context, the automatic compaction thresholds, checkpoints, and how to re-anchor after a summary replaces the middle of the session.
• Persistent memory for Claude Code and Codex — what Copilot Memory does and does not store, next to the instruction-file and MCP memory options.
• Hand off work between Claude Code and Codex — the written baton for work that moves between tools, including what carries over from a Claude Code setup to Copilot CLI.
• Gemini CLI guides — the same instruction, session, permission and hook problems in Google's terminal agent.
• Qwen Code guides — the same instruction, session, permission and hook problems in Qwen Code, the Gemini CLI fork.
• Cursor guides — the same instruction, session, permission and hook problems in Cursor, plus its rules, skills and MCP checks.

MCP: configured is not the same as usable#

An MCP server is an external process or service that gives the agent more tools. It is configured, then connected, then its tools are listed, then those tools are registered for the session, and then the agent can see them. /mcp list proves the first two steps. It does not prove the rest.

Use the next command when the list says "connected" but the agent says it has no tools:

copilot mcp get SERVER-NAME --json

That prints the server's type, status, and available tools. Inside a session, /mcp show SERVER-NAME shows the same status and tool list, and /env shows the loaded set across instructions, MCP servers, skills, agents, hooks, plugins, LSPs, and extensions.

The usual causes sit between those steps:

• The server is configured for a project that is not trusted. Project files load only after you confirm folder trust, and they are skipped in an untrusted directory. Prompt mode cannot show the trust prompt, so copilot -p skips project servers unless the directory is already trusted or you set GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=true.
• The configuration is in a file the CLI does not read. User servers live in ~/.copilot/mcp-config.json. Project servers live in .mcp.json in any directory from the working directory up to the repository root, or in .github/mcp.json. In the same directory, .mcp.json wins; closer files beat farther ones; project definitions beat user definitions. .vscode/mcp.json is not read because it uses the unsupported servers key.
• The server's tools list is narrower than you think. A server can be connected and expose only some tools, or none.
• The server is disabled, blocked by organization policy, or waiting on OAuth. A connected status is not an authorization to call every tool.
• The tools exist but cost too much context. Every server's tool schemas are part of the prompt. If a session starts nearly full, disable servers you are not using or narrow their tool lists.

The MCP setup page has the full configuration and trust rules, and the command reference covers the /mcp and copilot mcp commands.

Which settings file is actually read#

~/.copilot/settings.json is your user settings file. ~/.copilot/config.json is internal state, not a second settings file: user settings left in config.json are ignored, and have been since version 1.0.93. Use ~/.copilot/settings.json for preferences you want to keep.

Repository settings sit in .github/copilot/settings.json, with personal overrides in .github/copilot/settings.local.json. The CLI also reads .claude/settings.json and .claude/settings.local.json for a shared cross-tool subset: companyAnnouncements, disableAllHooks, enabledPlugins, extraKnownMarketplaces, and hooks. Other Claude settings keys are not a second configuration system.

The order is built-in defaults, MDM (mobile device management) managed settings, user settings, repository settings, local settings, environment variables, then command-line flags. Later entries override earlier ones, with two exceptions: managed permissions.disableBypassPermissionsMode always wins, and managed sandbox values set a floor you cannot relax. COPILOT_HOME replaces the whole ~/.copilot directory, and --config-dir is the legacy spelling of the same idea. Saved tool approvals do not live in settings.json: they live in permissions-config.json, keyed by location, and URL approvals live in allowedUrls in settings.json.

To check what a file is doing, read it through the same interface the CLI uses:

copilot config --list
copilot config --repo --list

The configuration directory reference has the full key list, the precedence table, and the per-scope rules. If a key seems ignored, check its spelling in the /settings Problems tab before you edit anything else.

Memory is on GitHub, not in `~/.copilot`#

Copilot Memory is a GitHub-side repository and user store in public preview, not a local file. Use it for learned facts; keep rules in an instruction file — the memory guide compares the options and covers the --enable-memory flag in copilot -p.