How to Use GitHub Agent HQ: Complete Guide (2026)

GitHub Agent HQ is the “neutral hub” for AI agents inside GitHub. One Copilot Pro+ subscription gives you access to Claude, Codex, Jules, Grok, Devin, and more — all invokable from issues and PRs. Here’s how to actually use it in April 2026.

Last verified: April 2026

Prerequisites

Requirement	Notes
GitHub account	Free account works
Copilot Pro+ subscription	$39/user/month as of April 2026
Repo access	Write permission to the repo
Branch protection (recommended)	Require PR review before merge

Step 1: Enable Copilot Pro+

1. Go to github.com/settings/copilot
2. Click Upgrade to Copilot Pro+
3. Confirm billing ($39/user/month, annual discount available)
4. Wait 1–2 minutes for entitlements to propagate

Organizations can enable Copilot Pro+ org-wide via Organization settings → Copilot → Plans. This billing model pools request credits across your team.

Step 2: Open Agent HQ

Agent HQ appears in two places:

1. Repo-level: In any repo, look for the Agent HQ tab next to Issues, Pull Requests, Actions.
2. Account-level: At github.com/copilot you’ll see an “Agent HQ” card showing all your recent agent runs across repos.

If you don’t see the tab, double-check Copilot Pro+ is active and the repo allows Copilot (Settings → Copilot).

Step 3: Configure Agent Permissions (Recommended)

Before you let agents touch code, set up guardrails:

Organization → Settings → Copilot → Agent HQ:

✅ Allow agents to open draft PRs
✅ Require human approval before agents push to protected branches
✅ Limit agent runs to labeled issues only
❌ Allow agents to merge PRs without review (KEEP OFF)

Repo → Settings → Branches → main:

✅ Require a pull request before merging
✅ Require review from CODEOWNERS
✅ Require status checks to pass

This ensures agents can draft PRs but can’t merge them without a human approver.

Step 4: Pick the Right Agent for the Task

Agent HQ’s killer feature is that different agents are good at different jobs. Route accordingly:

Task type	Best agent
Hard refactor, tricky debugging	Claude Opus 4.7
Large multi-file changes, fast	GPT-5.4 Codex
Auto-fix failing tests	Jules (Google)
Simple find-and-replace PRs	Grok Code (cheap, fast)
30+ minute autonomous runs	Devin (Cognition)
Routine tasks in your style	Copilot Agents

Step 5: Assign an Agent to an Issue

The primary workflow: open an issue, pick an agent, watch a PR appear.

1. Create or open a GitHub issue describing the task clearly
2. In the right sidebar, click Assignees → Agents
3. Pick the agent (e.g., Claude Opus 4.7)
4. Optionally add instructions via comment: @claude-opus-4-7 please use TypeScript and preserve existing test structure
5. Click Start Agent

The agent will:

• Read the issue and referenced files
• Clone the repo in an ephemeral sandbox
• Make changes
• Run tests
• Open a draft PR linked to the issue

Typical time: 5–20 minutes depending on agent and task complexity.

Step 6: Review the Agent’s PR

Agent PRs appear like any other PR with additional metadata:

• Agent identity — Clearly marked (e.g., “opened by Claude Opus 4.7 via Agent HQ”)
• Run trace — Full log of tool calls, files read, commands executed
• Cost summary — Tokens used and premium requests consumed
• Signed commits — All agent commits are GitHub-signed

Review workflow:

# Check out the agent's branch locally
gh pr checkout 42

# Run it
npm install && npm test

# Request changes via PR comment (the agent will iterate)

Leave a PR comment like @claude-opus-4-7 please also add a test for the edge case X and the agent will push a new commit.

Step 7: Run Multiple Agents in Parallel

The real power move: assign different parts of a feature to different agents simultaneously.

Example: Dark mode rollout across a React app:

1. Issue #101: “Update Button component for dark mode” → Grok Code (simple, fast)
2. Issue #102: “Migrate theme provider to CSS variables” → Claude Opus 4.7 (architectural)
3. Issue #103: “Update Storybook docs” → Jules (doc-writing)
4. Issue #104: “Add dark mode toggle in settings” → GPT-5.4 Codex (component + API)

All four PRs open in parallel, ~15 minutes each. You review sequentially and merge in dependency order.

Step 8: Use Agent HQ from CLI

For scripted workflows, use gh copilot agent:

# Start an agent on an issue
gh copilot agent start \
  --issue 101 \
  --agent claude-opus-4.7 \
  --message "Prefer test-driven approach"

# List active agent runs
gh copilot agent list

# Stream an agent run's output
gh copilot agent logs <run-id>

# Stop an agent
gh copilot agent stop <run-id>

Combine with gh issue create for end-to-end automation.

Step 9: Wire Agents into Workflows

Agent HQ integrates with GitHub Actions. Auto-trigger agents on events:

# .github/workflows/auto-fix-tests.yml
name: Auto-fix failing tests
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch Jules
        uses: github/copilot-agent-action@v1
        with:
          agent: jules
          task: "Fix the failing tests in the latest CI run"
          issue_title: "Auto-fix: CI failure in ${{ github.ref }}"

This runs Jules automatically whenever CI fails on main.

Step 10: Monitor Cost & Usage

Pro+ gives you 1,500 premium requests per user per month, pooled across agents. Check consumption at:

github.com/copilot/usage

Per-agent breakdown shows:

• Requests used per agent
• Average cost per PR
• Success rate
• Your actual productivity uplift (PRs merged / PRs attempted)

Common costs per agent task:

• Simple PR (under 5 files): 3–8 premium requests
• Medium refactor (10–30 files): 15–40 premium requests
• Large autonomous task (Devin): 80–200 premium requests

Best Practices

1. Write detailed issues. Agents perform 2–3× better when issues include file paths, acceptance criteria, and referenced docs.
2. Keep scope small. An issue that updates 5 files is better than one that updates 50. Break up big work.
3. Use CODEOWNERS religiously. Never let an agent merge without human review on critical paths.
4. Don’t route everything to Opus 4.7. It’s expensive. Use Grok Code for simple tasks.
5. Check the run trace. If an agent struggles, the trace shows you where — usually a missing file or unclear requirement.
6. Pair agents with tests. Agents with CI feedback loop iterate much better than agents working blind.

Troubleshooting

Problem	Fix
Agent doesn’t start	Check Copilot Pro+ is active and repo allows Copilot
Agent PR fails CI	Comment on PR with @agent please investigate
Agent runs out of context	Split the task into smaller issues
Hitting request limit	Route simple tasks to cheaper agents (Grok Code)
Agent writes wrong framework	Add project context in issue or CONTRIBUTING.md

Verdict

GitHub Agent HQ is the best way for teams to adopt AI coding at scale in April 2026. One subscription, multi-vendor agents, full audit trail, native GitHub integration. The workflow is: write a good issue, pick the right agent, review the PR, merge.

Start with low-risk tasks — doc updates, dependency bumps, failing-test fixes — and expand as your team builds trust in the agents. Within a few weeks most teams settle into a rhythm where 20–40% of merged PRs are agent-originated, with humans doing the high-leverage work of scoping, reviewing, and merging.