# How Copilot CLI works

The agent loop in GitHub Copilot CLI, traced on a hello world task - tools, approvals, context, models, sessions, rollback and modes.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/copilot-cli

This page covers Copilot CLI, the local terminal agent. Copilot in the IDE and the cloud agent are separate products.

## At a glance

| | Copilot CLI |
|---|---|
| Term | Agent session (started with `copilot`) |
| Configured in | `~/.copilot/` (override with `COPILOT_HOME`): `settings.json`, `permissions-config.json`, `mcp-config.json` |
| Runs | Interactive session, or one prompt with `copilot -p` that exits when done |
| Scope & precedence | Model: custom agent, then `--model`, then `COPILOT_MODEL`, then `settings.json`, then the default. Deny rules beat allow rules |

## Build the scenario

Start `copilot` in an empty folder, confirm that you trust it, and type the prompt from the [example scenario](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/example-scenario): `Create a hello world app in Python and run it.`

| Turn | Model asks for | Tool | What you see by default |
|---|---|---|---|
| 1 | Write `hello.py` | `create` | Approval prompt |
| 2 | Run it | `bash` (`powershell` on Windows) | Approval prompt |
| 3 | Nothing; it answers in text | none | The answer; the loop ends |

The docs don't say which tool names appear in a specific run, so treat the table as typical. Before writing, the model may also call read-only tools such as `view`, which run without asking.

Before turn 1, the first start asks whether you trust the folder: **1. Yes** (this session), **2. Yes, and remember this folder**, **3. No (Esc)**, which ends the session. For each tool call that changes things, you get:

| Choice | Effect |
|---|---|
| **1. Yes** | Allows this call; asks again next time |
| **2. Yes, and approve TOOL for the rest of the running session** | Allows that tool, with any options, until the session ends |
| **3. No, and tell Copilot what to do differently (Esc)** | Refuses; you can give feedback so it adapts |

The docs also describe "don't ask again in this repo/directory" choices that save to `permissions-config.json`. Run `/context` at any point to see tokens used against the model's window.

The same task in one command:

```bash
copilot -s -p "Create a hello world app in Python and run it." \
  --allow-tool='write, shell(python), shell(python3)'
```

`-p` runs one prompt and exits, `-s` prints only the answer. Without an allow flag, a call that needs approval has nobody to ask.

## Specifics

### Tools and approval

| Item | Detail |
|---|---|
| Built-in tools | `bash`/`powershell`, `create`, `edit`, `view`, `task` (subagents), plus `grep`, `glob` and `web_fetch` |
| Automatic | Reading, searching and read-only commands |
| Needs approval | Edits, non-read-only commands, URLs |
| Allow / deny | `--allow-tool`, `--deny-tool` with `Kind(argument)`; kinds are `shell`, `write`, `read`, `url`, `memory`, or an MCP server name |
| Hide from the model | `--available-tools`, `--excluded-tools` |
| Everything | `--allow-all-tools`, `--allow-all` / `--yolo` (tools, paths, URLs); `/allow-all` in a session |
| Reset | `/reset-allowed-tools` |

Depth: [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model).

### Models

| Task | How |
|---|---|
| Choose at start | `--model=MODEL` or `COPILOT_MODEL`; `--model=auto` lets Copilot pick |
| Switch in a session | `/model` (current session by default; `--global`, `--repo` persist it) |
| Auto tiers | `efficiency`, `balance`, `intelligence`, via `/model auto TIER` |
| See which model answered | The terminal shows the model used for each response |

### Context and compaction

| Item | Detail |
|---|---|
| Fills with | System prompt, tool definitions, instructions, messages, tool results |
| Inspect | `/context` (usage per category, free space, buffer) |
| Large tool output | Over 20 KiB goes to a temporary file; the model gets the path and a preview |
| Automatic compaction | Starts in the background at roughly 80% full; each compaction saves a checkpoint |
| Manual | `/compact [FOCUS-INSTRUCTIONS]`; `/session checkpoints` lists checkpoints |

### Sessions, undo, modes

| Need | How |
|---|---|
| Resume | `copilot --continue` (most recent), `--resume[=ID or name]`, `/resume` in a session |
| Start fresh | `/clear`, `/new` |
| Undo | `Esc` twice when idle, or `/undo` (`/rewind`): pick a prompt, rewind the conversation only or also restore files |
| Stop | `Esc` (twice while working), `Ctrl+C` (immediate) |
| Modes | `Shift+Tab` cycles the default mode, plan mode and autopilot; `--plan`, `--autopilot`, `--mode` set the start |
| Programmatic | `-p`; see [Headless execution](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution) |

Autopilot keeps working without your input; `--max-autopilot-continues` caps it. See [Loops](https://ai-sw-factory.mellicci.dev/fundamentals/loops).

## Gotchas

- `-p` with no allow flag cannot ask you, and autopilot with limited permissions denies whatever needs approval.
- `--allow-all` and `--yolo` give the agent your full file and shell access. Use them only in an isolated environment.
- Compaction is a summary and cannot be reversed. Details from early in a long session can be lost.
- Rewind is unavailable while work is in progress or in remote-backed sessions. Files over 10 MB and turns that changed more than 500 files are not restored.
- The docs disagree in two places: whether rewind also reverts your manual edits and deletes new files, and whether compaction starts at about 80% or 95% full. Check `git status` after a rewind.