GitHub Copilot Agent Mode: a step-by-step lab in VS Code

GitHub Copilot’s Agent mode in VS Code plans a task, edits files across your repo, runs terminal commands with your approval, and keeps going until the task is done or it needs you. This lab sets it up on a tiny Python repo: one instructions file, one agent task, one diff review, one test run. Everything below is matched against the current VS Code and GitHub Copilot documentation, with sources listed in the front matter.

What Agent mode actually does

VS Code’s Copilot Chat has three built-in modes, selected from the dropdown above the chat input: Ask answers questions and makes no edits, Plan writes a step-by-step plan and waits for you to approve it before anything changes, and Agent autonomously plans, edits files, runs terminal commands, and invokes tools until the task looks finished. You can switch modes mid-conversation.

This is a different split from older write-ups describing “Ask / Edit / Agent.” As of October 2026 the VS Code docs list Ask, Plan, and Agent as the three built-in modes, with no separate “Edit” mode in the chat UI. If you remember one thing: Agent is the mode that touches your files and your terminal without a per-hunk “apply” click.

Agent mode needs a model with tool-calling support, a workspace folder open, and chat.agent.enabled turned on (default true since VS Code 1.99). Sessions can also run Background (via the CLI, unattended) or Cloud (on GitHub’s infrastructure, opening a pull request) instead of Local; pick the session type next to the mode picker. This lab uses Local.

Step 1 — Open a tiny repo and check the basics

Create a throwaway folder and a two-file Python project:

# calculator.py
def total_with_discount(prices: list[float], discount_pct: float) -> float:
    """Return the total price after applying a percentage discount."""
    subtotal = sum(prices)
    return subtotal - discount_pct

# test_calculator.py
from calculator import total_with_discount

def test_discount_is_applied_as_percentage():
    assert total_with_discount([100.0, 50.0], 10) == 135.0

total_with_discount has a real bug: it subtracts discount_pct as a flat amount instead of a percentage, so the test above fails. Open the folder in VS Code, open Preferences: Open Settings (UI), and confirm chat.agent.enabled is true. Open the Chat view with Ctrl+Alt+I and confirm Ask, Plan, and Agent show up in the mode dropdown.

Step 2 — Write a repository custom instructions file

Repository-wide custom instructions live in .github/copilot-instructions.md, at the repo root, as plain Markdown:

<!-- .github/copilot-instructions.md -->
This is a small Python project that uses pytest.

- Use type hints on every function signature.
- Keep business logic in calculator.py; keep tests in test_*.py files next to it.
- When you fix a bug, add or update a test that would have caught it.
- Run `pytest -q` after making a change and report the result.

Once saved, VS Code and Copilot on GitHub.com both pick this up automatically for every chat request in the repo — no toggle to flip. For rules that apply only to certain files, add a path-specific instructions file instead: create .github/instructions/python.instructions.md with an applyTo front matter block:

---
applyTo: "**/*.py"
---
Prefer explicit return types. Avoid bare `except:` clauses.

Repository-wide and matching path-specific instructions are combined, not one-or-the-other — keep them non-contradictory. On GitHub.com itself, path-specific instructions currently apply only to the cloud agent and to Copilot code review; in VS Code, both files apply to chat and agent sessions.

Step 3 — Optional: add a reusable prompt file

A prompt file is a saved slash command. Create .github/prompts/fix-and-test.prompt.md:

---
description: Fix a failing test and verify with pytest
agent: agent
---
Run `pytest -q`. Read the first failing test and the function it tests.
Fix the implementation, not the test, unless the test itself is wrong.
Re-run `pytest -q` and report the result.

The agent field pins this prompt to Agent mode regardless of the current selection; a tools field can restrict which tools or MCP tools the prompt may call. Type /fix-and-test in the chat input to run it.

Step 4 — Run an agent task and approve the terminal command

Back in the Chat view, with Agent selected, send:

pytest is failing in test_calculator.py. Find out why and fix it.

The agent reads both files, proposes an edit to total_with_discount, and — because pytest -q is a new command in this session — pauses with a confirmation prompt first. Review the command shown, then choose Allow to run it or Skip to redirect the agent. Nothing runs without that prompt unless the command is pre-approved via chat.tools.terminal.autoApprove.

A reasonable fix for the bug:

# calculator.py
def total_with_discount(prices: list[float], discount_pct: float) -> float:
    """Return the total price after applying a percentage discount."""
    subtotal = sum(prices)
    return subtotal * (1 - discount_pct / 100)

Step 5 — Review the diff, then run the tests yourself

Agent-mode edits land as pending changes in the editor, shown as a diff against the file on disk. Review them in place and choose to keep or discard each one — the docs are explicit that you decide which changes to accept, the agent does not commit for you. Don’t skip this step just because the agent reported success: read the actual diff, not just the chat summary.

Once you’ve kept the edit, confirm it yourself outside the chat, with the same command you’d run normally:

pytest -q

If it passes, you’re done with the local loop. If it still fails, send the agent the new failure output rather than re-describing the bug from memory — a pasted stack trace or assertion message is a much stronger delegation than “it’s still broken.”

Tools and MCP servers in VS Code

Agent mode calls tools: built-in ones (read file, edit file, run terminal command, search workspace) plus anything exposed by extensions or by MCP servers you configure. MCP is the same open protocol covered in the MCP servers guide — VS Code is one more client for it.

Run MCP: Add Server from the Command Palette, choose HTTP for a URL-based server or Command (stdio) for a local one, and pick Workspace (writes .vscode/mcp.json, shareable via source control) or your user profile. A minimal workspace file:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Every tool call, built-in or MCP, goes through the same approval flow as a terminal command the first time it runs, unless pre-approved. Local MCP servers run arbitrary code with your permissions — only add ones from sources you trust.

The cloud agent on GitHub issues and pull requests

Everything above runs inside VS Code, against files on disk. GitHub also ships a cloud-hosted agent that works directly on GitHub.com. Open an issue, click Assignees in the right sidebar, and select Copilot. Add optional guidance in the prompt field and pick the target repository, base branch, and model. Assigning the issue always produces a pull request — Copilot works on a branch in the background and requests your review when done. It only sees the issue’s title, description, and comments as they existed at assignment time, so post later updates as a comment on the resulting pull request, not the original issue.

Copilot code review on a pull request

Separately from the cloud agent, you can ask Copilot to review any pull request’s diff. Open the PR, find Copilot under Reviewers, and click Request. It typically responds in under 30 seconds with comments labeled High, Medium, or Low severity, often with one-click suggested fixes. From the GitHub CLI:

gh pr create --reviewer @copilot
# or, on an existing PR:
gh pr edit PR-NUMBER --add-reviewer @copilot

By default this leaves a Comment review, not an Approve or Request-changes review, so it doesn’t by itself satisfy a required-approvals rule.

Choosing a model

The model picker sits at the bottom of the chat input, independent of which mode you’re in. Auto routes each request to a model based on task complexity and current availability — hover the response to see which one answered. Open Manage Language Models (gear icon in the picker, or the Chat: Manage Language Models command) to check context size and capability per model, hide unused ones, or add a model via your own API key.

Pitfalls

You approved a command once, not forever. chat.tools.terminal.autoApprove matches specific commands or regex patterns; it is not a blanket “stop asking.” The global chat.tools.global.autoApprove setting removes the approval step for every tool, and VS Code’s own description calls it out as disabling a critical security protection — don’t flip it on a machine with anything you care about.

Instructions files don’t fix a bad run retroactively. .github/copilot-instructions.md shapes new requests; it doesn’t rewrite a plan the agent already committed to mid-task. If a session goes sideways, fix the instructions and start fresh rather than nudging the same context.

Path-specific instructions aren’t universal yet. On GitHub.com, .github/instructions/*.instructions.md files currently apply to the cloud agent and to Copilot code review, not every Copilot surface on the site. In VS Code they apply more broadly, to chat and agent sessions. Don’t assume one client matches another — exactly the kind of detail covered in Claude Code vs. Copilot vs. Cursor.

“Reviewed by Copilot” isn’t “approved by a human.” A Copilot code review leaves comments, not an approval that satisfies branch protection. Treat it as a fast first pass, the same way you’d treat a step in an AI-assisted TDD workflow: useful signal, not a merge gate.

The cloud agent can’t see new issue comments. It freezes the issue content at assignment time. Add follow-ups to the resulting pull request, not the issue, or the agent never reads them.

FAQ

What is GitHub Copilot agent mode in VS Code?

Agent is one of the built-in chat modes in VS Code, alongside Ask and Plan. In Agent mode, Copilot Chat plans the work, edits files across your workspace, runs terminal commands, and iterates on the result with full autonomy, instead of waiting for you to approve each edit individually.

How do I turn on agent mode in VS Code?

Open the Chat view and pick Agent from the agent/mode dropdown above the chat input. The underlying setting is chat.agent.enabled, which defaults to on in VS Code 1.99 and later. If you don’t see Agent in the dropdown, check that setting and update VS Code.

Does Copilot agent mode run terminal commands without asking?

No, not by default. The first time an agent wants to run a new terminal command it pauses and asks you to Allow or Skip it. You can pre-approve specific commands with chat.tools.terminal.autoApprove, but the global auto-approve setting explicitly disables a safety protection and is off by default.

What’s the difference between .github/copilot-instructions.md and a .instructions.md file?

.github/copilot-instructions.md holds repository-wide instructions that apply to every Copilot request in that repo. A NAME.instructions.md file under .github/instructions/ carries an applyTo glob in its front matter and only applies to matching file paths, which keeps framework- or language-specific rules out of the main instructions file.

Can Copilot open a pull request by itself?

Yes. Assign a GitHub issue to Copilot from the Assignees menu, or start a cloud agent task from the agents panel, and Copilot works on a branch and opens a pull request for you to review. You can also ask for a Copilot code review on any existing pull request from the Reviewers sidebar.