GitHub Copilot as a coding agent: cloud agent, app, CLI and billing

GitHub Copilot is a full coding-agent platform, not only an autocomplete: a cloud agent that researches, plans and changes code on a branch in GitHub Actions and opens a pull request, a desktop Copilot app and Copilot CLI for local work, Agent Skills, hooks and MCP, and third-party Claude and Codex agents. Since 1 June 2026 its agent and chat usage bills in usage-based GitHub AI Credits.

Checked 26 September 2026

Verified against GitHub’s documentation source (github/docs, main branch) and a local install of Copilot CLI 1.0.88 (copilot --help). Third-party agents, gh skill and AI-credit session limits are public previews, CLI sandboxing is experimental, and all change often. Model prices live on the models hub.

Your company already pays for Copilot Business. A developer wants Claude Code, a tech lead wants to hand backlog issues to an agent, and finance asks why the June invoice changed. Before you buy another seat, learn what Copilot’s agents do, what a task costs, and which controls to set before the first agent pull request.

What this GitHub Copilot reference gives you

• A map of the five Copilot agent surfaces and the job each one fits.
• A working copilot-setup-steps.yml, a preToolUse hook, and three copy-paste prompts for the cloud agent and the CLI.
• How AI-credit billing works and which knobs cap spend.
• An admin checklist for Business and Enterprise, including policy gaps the settings pages do not flag.
• A decision table for when Copilot is enough and when to add Claude Code, Codex or Cursor.

JetBrains’ August 2026 research (secondary, search extracts) places Copilot among the top AI coding tools used at work, behind Claude Code. For many teams it is the first agent; the question is how far it goes.

Which GitHub Copilot surface fits which job?

The five surfaces share one account, one AI-credit allowance and most customisation files. They differ in where the agent runs and who watches it.

Surface	Where the agent runs	How you start it	Fits
Copilot cloud agent	An ephemeral GitHub Actions environment	Assign an issue to Copilot, the Agents tab, @copilot on a pull request, Slack or Teams, or an automation	Well-specified backlog issues, test gaps, dependency and documentation chores
GitHub Copilot app	Your desktop (macOS, Linux, Windows), one git worktree and branch per session; cloud or local sandbox	Pick an issue or start a blank workspace, choose Interactive, Plan or Autopilot	Several parallel tasks you steer and review from one window
Copilot CLI (@github/copilot 1.0.88)	Your terminal, or headless with -p	copilot, copilot --plan, copilot -p "…"	Terminal-first work and scripted jobs in CI
Agent mode in VS Code and JetBrains	Your editor, editing local files	The chat view’s agent picker	Interactive changes where you watch each edit
Third-party agents (public preview)	The same GitHub-hosted environment as the cloud agent	Assign an issue to the Claude or Codex agent, or mention it on a pull request	Comparing agents on the same issue without separate subscriptions

GitHub’s plans page states that “All plans include Copilot CLI and GitHub Copilot app”. The cloud agent needs a paid plan: it is on by default for Pro, Pro+ and Max, and off by default for Business and Enterprise until an administrator enables it.

How do you delegate an issue to the Copilot cloud agent?

The cloud agent works best when the environment is deterministic and “done” is written down. Do these in order.

1. Enable the agent. On Business or Enterprise, an organization owner enables the cloud agent policy (see the admin checklist below). Repository owners can opt individual repositories out.

2. Give it instructions it will read. The cloud agent reads .github/copilot-instructions.md, path-specific .github/instructions/**/*.instructions.md, organization instructions, and agent files: AGENTS.md, CLAUDE.md or GEMINI.md. An existing AGENTS.md or CLAUDE.md works as is; keep build, test and “definition of done” commands there. See making a codebase agent-ready.

3. Pre-install the toolchain with copilot-setup-steps.yml. Without it, the agent finds dependencies by trial and error and fails on private packages. The file must live at .github/workflows/copilot-setup-steps.yml, contain a single job named copilot-setup-steps, and be on the default branch before it takes effect:

   .github/workflows/copilot-setup-steps.yml

   name: "Copilot Setup Steps"
   on:
     workflow_dispatch:
     push:
       paths:
         - .github/workflows/copilot-setup-steps.yml
   jobs:
     copilot-setup-steps:          # the job name is mandatory
       runs-on: ubuntu-latest
       timeout-minutes: 40         # hard ceiling is 59
       permissions:
         contents: read            # Copilot gets its own token for its work
       steps:
         - uses: actions/checkout@v4
           with:
             persist-credentials: false   # Copilot uses its own token; do not leave the job token in .git/config
         - uses: actions/setup-node@v4
           with:
             node-version-file: .node-version
             cache: npm
         - run: npm ci
         - run: npx playwright install --with-deps chromium

   Only steps, permissions, runs-on, services, snapshot and timeout-minutes are honoured; other job settings are ignored. Run the workflow once from the Actions tab to prove it is green.

   Credentials for a private registry go in Settings → Secrets and variables → Agents, at repository or organization level. Secrets once kept in the copilot Actions environment were migrated there automatically, and the agent cannot read Actions, Codespaces or Dependabot secrets. Agents secrets reach the setup steps and the agent itself as environment variables, so store only read-only, narrowly scoped tokens there. Only names prefixed COPILOT_MCP_ are hidden from the agent and passed to MCP servers alone.

4. Write the issue as a spec. Put the acceptance criteria, the files in scope and the command that proves the work into the issue body, as in the prompt below. See writing acceptance criteria an agent can check.

5. Assign the issue to Copilot, or ask it in the Agents tab to plan first. Planning before a pull request works only on github.com (preview in Slack and Teams); Jira, Linear and Azure Boards go straight to a pull request.

6. Review and iterate with @copilot comments on the pull request. It pushes new commits to the same pull request.

Copy-paste prompt: an issue body the cloud agent can finish

Add rate limiting to POST /api/auth/login.

Acceptance criteria:
- More than 5 failed attempts per email within 15 minutes returns HTTP 429
  with a Retry-After header; the 6th attempt must not reach the password check.
- A successful login resets the counter for that email.
- Limits are stored in the existing Redis client in src/lib/redis.ts; do not add a new dependency.

Scope: src/routes/auth/login.ts, src/lib/rate-limit.ts (new), tests/auth/login.rate-limit.test.ts (new).
Out of scope: signup, password reset, any UI change.

Done means:
- npm test -- tests/auth passes, including new tests for the 429 path, the reset path,
  and the Retry-After value.
- npm run lint and npm run typecheck pass.
- The pull request description lists each acceptance criterion with the test name that proves it.
Stop when these pass. Do not refactor unrelated code.

The cloud agent has four hard limits (checked 2026-09-26): one repository per task, one branch and at most one pull request per task, a maximum session time of 59 minutes that cannot be extended, and repositories hosted on GitHub only. If an issue cannot finish in under an hour, split it by acceptance criterion before you assign it.

How do you run Claude and Codex agents inside Copilot?

GitHub runs two third-party agents in public preview: Anthropic Claude (built on the Claude Agent SDK) and OpenAI Codex. They share the cloud agent’s entry points, protections and limits, and draw on your AI credits and Actions minutes. Only the code author and the model list differ.

Copilot cloud agent

Assign the issue to Copilot, or mention @copilot on a pull request. It uses the full Copilot model list for your plan (on Pro+, Max, Business and Enterprise that includes Claude Opus 5.5, GPT-6 Astra and GPT-6 Sol), plus custom agents, hooks, skills and repository MCP settings. Pick it by default: it has the most customisation.

Anthropic Claude

Enable Allow Claude coding agent (it installs the anthropic code agent GitHub App, visible in your audit log), then assign the issue to the Claude agent or mention it on a pull request. On 2026-09-26 GitHub’s docs list Auto, Claude Opus 4.7 and Claude Sonnet 4.6 for this agent, and Claude Opus 4.7 is scheduled to leave Copilot on 2026-10-02. To run Claude Opus 5.5 on an issue, use the Copilot cloud agent with that model or run Claude Code in your CI.

OpenAI Codex

Enable Allow Codex coding agent, which installs a GitHub App named openai code agent. On 2026-09-26 GitHub’s docs list Auto, GPT-5.3-Codex, GPT-5.4 and GPT-5.4 nano for this agent, while Codex itself defaults to GPT-6 Astra. For current OpenAI models on an issue, pick GPT-6 Astra or GPT-6 Sol in the Copilot cloud agent, or use Codex’s own GitHub Action.

Auto in the third-party agents picks one of that agent’s listed models; it is not Copilot’s auto model selection and does not earn its 10% discount. Use the preview agents to compare harnesses on one issue. If your team standardises on Claude Code or Codex, run them natively; the head-to-head page compares the two paths.

Work locally with Copilot CLI and the Copilot app

Install the CLI with any of the documented methods (npm needs Node.js; check the install page for the minimum version):

Terminal

npm install -g @github/copilot          # all platforms
brew install --cask copilot-cli         # macOS and Linux
winget install GitHub.Copilot           # Windows
copilot --version                       # GitHub Copilot CLI 1.0.88 on 2026-09-26

The flags that matter for agent work, all present in copilot --help 1.0.88:

Flag or command	What it does
--plan, --mode plan|interactive|autopilot, --autopilot	Start in plan mode or fully autonomous mode; Shift+Tab cycles modes in a session
--max-autopilot-continues <count>	Caps automatic continuations in Autopilot (default 5)
--max-ai-credits <credits>, /limits set max-ai-credits N	Soft AI-credit cap per session (minimum 30; public preview per GitHub’s “Set an AI Credit limit” how-to)
--allow-tool, --deny-tool, --allow-all-tools	Tool permissions; a deny rule always wins, even over --allow-all-tools
--allow-all / --yolo	Tools, paths and URLs all allowed; use only inside a sandbox
/sandbox enable	OS-level sandbox for shell commands (experimental: start with --experimental or run /settings experimental on first; Linux needs bwrap)
-p, -s, --output-format json, --usage-output-file	Headless runs for scripts and CI, with JSONL output and a usage report
--model, --reasoning-effort	Model and effort (none through max) for the session
--fleet	Runs the prompt with parallel subagent orchestration
copilot app	Opens the GitHub Copilot app

The GitHub Copilot app is built on the CLI. Each session gets its own git worktree and branch, runs in a cloud or local sandbox, and uses one of three modes: Interactive, Plan (you approve the plan) or Autopilot. GitHub advises switching to Autopilot only when the task is well defined. The app also runs scheduled Automations and reads the same instructions, MCP servers and skills as the CLI.

Copy-paste prompt: a capped, headless Copilot CLI run for CI

Read the failing job log in ci-output.txt. Find the root cause of the failing test,
fix the code (not the test) unless the test contradicts the acceptance criteria in
docs/specs/billing.md, and run npm test -- tests/billing until it passes.
Write a summary to fix-report.md with: root cause, files changed, and the exact
test command and its final output. Do not push, do not open a pull request.

Save the prompt above as .github/prompts/fix-ci.txt. Authenticate with the job’s built-in token, which GitHub recommends for automations in organization repositories: it is short-lived and scoped to the run, so no long-lived credential is stored. Give the workflow permissions: contents: read and copilot-requests: write, and pass GITHUB_TOKEN: ${{ github.token }} in the step’s env. In an organization repository, usage is billed to the organization and an owner must enable the Allow use of Copilot CLI billed to the organization policy; this needs a recent CLI version. Fall back to a fine-grained personal access token with only the Copilot Requests permission, stored as a repository secret and passed as COPILOT_GITHUB_TOKEN, only where the built-in token is not available. A classic ghp_ token is not supported. Then run the prompt from the repository root in the CI job:

# env: GITHUB_TOKEN: ${{ github.token }}; workflow permissions: contents: read, copilot-requests: write
copilot -p "$(cat .github/prompts/fix-ci.txt)" \
  --allow-tool='shell(npm:*)' --allow-tool=write --no-ask-user \
  --disable-builtin-mcps --secret-env-vars=GITHUB_TOKEN \
  --max-ai-credits 150 --output-format json --usage-output-file copilot-usage.json

A -p run cannot show an approval prompt, so any tool outside the allow-list, including git push, is denied. --disable-builtin-mcps turns off the built-in GitHub MCP server, so the agent cannot open a pull request through it. --secret-env-vars strips the token from the agent’s shell environment and redacts it from output. Even so, treat the token as readable by the agent: with write and npm allowed it can edit package.json and run arbitrary code. Never use --allow-all-tools here. Run the job only on an ephemeral runner with no permissions beyond contents: read and copilot-requests: write and with persist-credentials: false, and never on a fork’s pull request or other untrusted ref, where the token, or a fallback PAT secret, would meet attacker-controlled code. For most automation GitHub recommends GitHub Agentic Workflows, which add guardrails, over raw copilot -p steps.

Extend Copilot with skills, hooks and MCP

Most of these files are shared with other agents, which matters if your team runs more than one tool.

Agent Skills. Copilot follows the open Agent Skills standard on every surface. It loads project skills from .github/skills, .claude/skills or .agents/skills, and personal skills from ~/.copilot/skills or ~/.agents/skills. A Claude Code skill in .claude/skills works unchanged. Install shared skills with gh skill (GitHub CLI 2.90.0 or later; preview), and read each skill first, because GitHub does not verify them:

Terminal

gh skill search "release notes"
gh skill preview github/awesome-copilot documentation-writer   # renders SKILL.md, installs nothing
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

Hooks. Hooks run shell commands at session, prompt and tool events for the cloud agent and the CLI. Repository hooks live in .github/hooks/*.json; the CLI also reads personal hooks from ~/.copilot/hooks/. A preToolUse hook can deny a tool call, which makes it the one place to enforce a rule the agent cannot talk its way around:

.github/hooks/guard.json

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      { "type": "command", "bash": "./.github/hooks/deny-risky.sh", "timeoutSec": 5 }
    ]
  }
}

.github/hooks/deny-risky.sh

#!/usr/bin/env bash
payload="$(cat)"
if printf '%s' "$payload" | grep -Eq 'git push --force|rm -rf /|DROP TABLE|terraform apply'; then
  echo '{"permissionDecision":"deny","permissionDecisionReason":"Blocked by repository policy in .github/hooks/deny-risky.sh"}'
fi

A crash or non-zero exit in a preToolUse command hook denies the call, but a timeout lets the call through. Keep the script fast and set timeoutSec well above its real run time. Under the cloud agent, a decision of ask counts as deny, because nobody is there to answer.

MCP. The cloud agent starts with two MCP servers on: GitHub’s, using a token scoped read-only to the current repository, and Playwright, limited to localhost. Repository administrators add more as JSON in the repository’s Copilot settings; they apply to the cloud agent and Copilot code review. The agent uses configured tools without asking, so list only the tools it needs. Locally, the CLI reads ~/.copilot/mcp-config.json and a workspace .mcp.json or .github/mcp.json, and ships the GitHub MCP server by default:

Terminal

copilot mcp add playwright -- npx @playwright/mcp@latest
copilot mcp list

How does Copilot’s AI-credit billing work?

Since 1 June 2026 Copilot bills by model and tokens, not by request. Every interaction’s input, output and cached tokens are priced at the chosen model’s rate and converted to GitHub AI Credits at 1 credit = $0.01. Premium requests and model multipliers survive only on legacy annual Pro and Pro+ plans until they end.

Plan	Price	Base credits per month	Flex allotment on top
Free · Student	$0	a smaller allowance, Auto model selection only (Free: 2,000 completions per month)	—
Pro	$10/month	1,000	+500
Pro+	$39/month	3,900	+3,100
Max	$100/month	10,000	+10,000
Business	$19/user/month	1,900 per user	not listed per plan
Enterprise	$39/user/month	3,900 per user	not listed per plan

Base credits match the subscription price. GitHub calls flex “a variable part of your included usage”, so budget on base credits only. Allowances reset at 00:00 UTC on the first of each month and do not roll over. Code completions and next edit suggestions are not billed in credits on paid plans. The cloud agent and third-party agents also consume GitHub Actions minutes, which is the line item teams forget.

To estimate one task, multiply its tokens by the model’s per-million-token rates on the models hub and multiply the dollar result by 100 to get credits. Four levers cut spend without cutting quality, all from GitHub’s own guidance:

• Pick the model per task, then keep it. Switching model, effort, context size or MCP tools mid-session invalidates the cache and rebills the whole context.
• Use Auto model selection as the default. Paid plans get a 10% discount on model costs with it in Chat, the CLI, the app and the cloud agent.
• Cap sessions. Use --max-ai-credits in the CLI, and user or cost-centre budgets for the monthly total (cost governance covers the budget design).
• Plan with a strong model, implement with a cheaper one. Subagents do not inherit the main conversation, so a lighter model there does not break its cache.

Set org policy before the first agent pull request

Copy this checklist into your rollout ticket.

Admin checklist for Copilot Business and Enterprise

• Cloud agent policy: default off on Business and Enterprise; enable per organization, or per enterprise if the enterprise controls it.
• Repository opt-outs: exclude repositories with regulated data or no test suite.
• Automations: on by default wherever the cloud agent is on; any user with write access can create one. Decide whether that is acceptable.
• Third-party agents (Claude, Codex): separate policies; enabling one installs its GitHub App.
• GitHub Copilot app policy: on by default and separate from the Copilot CLI policy.
• Content exclusion: the app and CLI respect enterprise, organization and repository exclusions; confirm yours cover secrets and customer data.
• MCP policy: the CLI cannot enforce the “MCP servers in Copilot” policy or the MCP Registry URL policy (Copilot CLI 1.0.88, per about-copilot-cli, checked 2026-09-26). GitHub’s enterprise admin page says MCP allowlist policies do apply, so test the policy on a CLI install before relying on it; meanwhile enforce local MCP use another way, for example with a preToolUse hook.
• Runner and firewall: set the default runner type for the cloud agent and review its firewall allowlist.
• Rulesets: rules that restrict commit authors block the agent; add Copilot as a bypass actor only on rules where that is safe.
• Budgets: set spending limits before the first month closes, not after.

For the cross-vendor version of this policy (Claude Code managed settings, Codex requirements.toml, Cursor and Copilot on one page), see one policy for every coding agent.

How do you verify what Copilot’s agents produce?

An agent pull request is a claim, not a result. Make it checkable before anyone reads the diff.

• The agent runs your gates. copilot-setup-steps.yml installs the toolchain so the agent runs tests, lint and type checks inside its session, and your normal required status checks run on its pull request. Actions workflows on an agent pull request wait until someone with write access approves them. Approve the run before judging the checks, and put any secrets the setup steps need in Settings → Secrets and variables → Agents. Treat a red check exactly as you would for a human.
• GitHub scans agent code. For the cloud agent and the third-party agents, GitHub documents automatic security validation before the pull request is finalized: CodeQL code scanning, secret scanning, and a check of new dependencies against the GitHub Advisory Database, with no GitHub Advanced Security licence required.
• Hooks enforce what prompts cannot. A preToolUse deny is deterministic; an instruction in AGENTS.md is a request.
• The pull request carries evidence. Ask the agent to map each acceptance criterion to a test and paste the command output. That is the evidence bundle reviewers check instead of reading every line.
• A named human signs off. The agent requests your review when it finishes; branch protection and CODEOWNERS decide who merges. Keep that decision with the engineer who owns the acceptance criteria.
• Measure outcomes, not activity. The Copilot usage metrics APIs report pull requests created and merged (including cloud-agent ones) and median time to merge. Track merge rate and rework per agent next to your delivery metrics.

Copy-paste prompt: a @copilot comment that turns a pull request into evidence

@copilot Before I review: update the pull request description with a table that maps
each acceptance criterion in the linked issue to the test that proves it (file and test
name). Run the full test suite, lint and typecheck, and paste the exact commands and
their final output lines. List every file you changed that is outside the scope listed
in the issue and explain why, or revert those changes. Do not change behaviour in this pass.

What breaks with Copilot’s agents, and how do you recover?

• The agent never starts, or cannot push. A ruleset restricting commit authors blocks it. Check the session log, then add Copilot as a bypass actor or relax the rule for agent branches.
• Setup steps fail silently. If a step exits non-zero, Copilot skips the rest, starts in a half-built environment and burns credits reinstalling. Run the workflow from the Actions tab until green, and keep it on the default branch.
• Credits run out mid-month. On an individual plan, upgrade (you pay the difference), set a budget for extra usage, or wait for the monthly reset; on Business and Enterprise the budget is the lever. Put --max-ai-credits on every scripted run and review /usage per session.
• A model disappears. Claude Opus 4.7, Kimi K2.7 Code, Gemini 3.5 Flash and Gemini 3.6 Flash leave Copilot on 2026-10-02. Automations and scripts pinned to them need a new --model; check the models hub before you pin one.
• A timed-out hook lets a blocked command through. See the timeout note under hooks.
• An installed skill carries a prompt injection. Run gh skill preview before every install and pin versions with --pin.
• --allow-all-tools or --yolo on a workstation. The agent gets your full file and shell access. Run such sessions in a sandbox, a container or CI with a scoped token; see permissions and sandboxing.

When is Copilot enough, and when do you add Claude Code or Codex?

Your situation	Recommendation
Code lives on GitHub, work arrives as issues, and you want pull requests from the backlog	Start with the Copilot cloud agent; you already pay for it
Engineers want a terminal agent with a deep hook, subagent and plugin ecosystem	Add Claude Code for those engineers, and keep Copilot for issue-driven work
You need OpenAI’s current default model in its own harness, or multi-surface cloud tasks	Add Codex; the Codex agent inside Copilot offers older models
Code is not on GitHub	The cloud agent does not apply; compare the other coding agents
You must keep one bill and one admin console	Stay on Copilot and use its model picker, including Claude Opus 5.5 and GPT-6 Astra on Pro+, Max, Business and Enterprise (not Pro)

Where to go next with GitHub Copilot

• Cursor, Claude Code and Codex vs GitHub Copilot: the head-to-head comparison.
• Adding Claude Code or Codex alongside Copilot: the team migration path.
• From issue to pull request with no hands on the keyboard: the cross-tool pipeline.
• Background and cloud agents compared: Copilot’s cloud agent next to Claude Code on the web, Codex cloud and Cursor Cloud Agents.
• The GitHub MCP server: Copilot’s default server, for other agents.
• The coding-agent landscape beyond the big three: where Copilot sits among Gemini CLI, Kiro, OpenCode and the rest.