Background Delegation

What It Is

Background Delegation hands off tasks to a cloud-based Copilot coding agent on GitHub. Your terminal is immediately freed. The agent works on a branch in GitHub, and you review the result there — as a branch diff or as a PR when you ask Copilot to create one.

This is distinct from async PowerShell (for local long-running processes like builds/servers), which still uses mode: "async" in the powershell tool.

When to Use

• Large refactors or multi-file migrations you don't want to block on
• Full test suite additions or comprehensive documentation generation
• Complex tasks where you want research or an implementation plan before any code is written
• Any task that benefits from running in a fresh, isolated context on GitHub
• Handing off work while you continue unrelated local development

When NOT to Use

Instead of background-agent	Use
A small, well-scoped edit you can finish immediately	Work directly in the current session
A local build, dev server, watcher, or test run	Async PowerShell with mode: "async"
A read-only query where you need the answer right away	Answer directly in the current session
A task that depends on local-only services, hardware, or unshared secrets	Keep the work local rather than delegating to GitHub

Cloud Agent Deep Work Mode

For complex tasks where architectural analysis matters before implementation, ask the cloud agent to research first and present a plan before it edits files.

1. Research: Copilot investigates the codebase, dependencies, and current behavior
2. Plan: Copilot proposes an implementation approach before writing code
3. Review: You refine or approve the approach on GitHub
4. Implement: Copilot executes the approved plan on the branch

When to use deep work vs direct delegation

Scenario	Use
Large refactor across many files	Research + plan first
Architecture change with unclear scope	Research + plan first
Small, well-scoped change	Direct delegation with & or /delegate
Repetitive bulk operation	Direct delegation with & or /delegate

Example:

/delegate Analyze the current auth flow, propose a hardening plan, and wait for approval before changing code

Treat the plan as the approval surface. Iterate on the approach first, then let the agent implement once the direction is clear.

Workflow

1. Delegate with & or /delegate

Prefix any prompt with & to push the task to the cloud Copilot coding agent:

& "Add pagination to all REST endpoints and write integration tests"

Equivalently, use the slash command:

/delegate Add pagination to all REST endpoints and write integration tests

The agent commits any of your unstaged changes as a checkpoint, creates a new branch, and begins working on GitHub.

2. Continue Local Work

Your terminal is free. Keep coding locally while the agent works on GitHub. For unattended local runs, do not assume that the end of an agent turn means every background shell or child agent has exited; verify child-process completion because surviving children have caused real prompt-mode hangs.

3. Review the Branch or PR

By default, review the resulting work on GitHub. Depending on how you prompted the task, Copilot may leave the work on a branch for diff review or create a PR when you ask for one. Do not treat terminal polling as the primary review path; the GitHub branch or PR is the canonical output.

4. Continue the Conversation Locally (Optional)

Use /resume to bring a cloud agent session into your local CLI, preserving the full accumulated context:

/resume
# → Select from list of recent sessions

/resume abc123
# → Resume a specific session by ID
> Now also update the API documentation to reflect the pagination parameters

Note: /resume is for continuing the conversation, not polling for results. The agent's output is reviewed on GitHub first.

5. Async PowerShell — Local Long-Running Processes

For local processes (builds, dev servers, test watchers) that don't need cloud delegation, use async PowerShell:

# Start dev server (persists in background)
Tool: powershell
  command: "npm run dev"
  mode: "async"
  detach: true

# Run tests in async mode
Tool: powershell
  command: "npm test -- --watchAll"
  mode: "async"
  → Returns: shellId

# Read output later
Tool: read_powershell
  shellId: "test-session"
  delay: 5

Examples

Delegate a Large Migration

# Hand off to cloud agent — terminal is immediately free
& "Migrate all class components in src/ to React hooks"
# → Review the resulting branch or PR on GitHub

# Continue local work while agent runs
> Now let's update the design system tokens...

Parallel Delegations

# Delegate two independent tasks simultaneously
& "Add comprehensive error handling to all API endpoints"
# → Work starts on GitHub for task 1

& "Generate JSDoc for all exported functions in src/services/"
# → Work starts on GitHub for task 2

# Both run concurrently on GitHub while you work locally

Multi-Turn Refinement

# Initial delegation
& "Analyze the auth system and refactor weak points"

# After reviewing the branch or PR...
/resume abc123
> The token refresh logic still has a race condition — fix it too
# → Agent continues with full context from the original session

Local Build + Test (Not Delegation)

# These stay local — use async PowerShell, not &
powershell mode="async": npm run build
powershell mode="async": npm test -- --watchAll
powershell mode="async" detach=true: npm run dev

Tips

• & delegates to GitHub cloud — review the resulting branch or PR on GitHub.
• Ask for research first when the task is ambiguous: tell Copilot to analyze and propose a plan before it edits code.
• Async PowerShell is for local processes — builds, servers, watchers. No PR created.
• /resume for context continuity — bring the session local to keep iterating after the GitHub review.
• Unstaged changes are committed — Copilot creates a checkpoint commit before branching.
• Review on GitHub — the canonical output is the GitHub branch or PR, not terminal polling.