background-agent

---
name: background-agent
description: Use when a task is too long to block the current session or should run autonomously — delegates to a cloud background agent via & or /delegate so work can continue on GitHub while you keep moving locally, not in a local async PowerShell session.
metadata:
  category: copilot-exclusive
  copilot_feature: "Background Delegation (&, /delegate), cloud Copilot coding agent, branch/PR workflows, /resume"
---

# 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:

```text
/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:

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

Equivalently, use the slash command:

```text
/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:

```text
/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:

```text
# 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

```text
# 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

```text
# 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

```text
# 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)

```bash
# 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.

More agent context in drvoss/everything-copilot-cli

111 other files this repository gives its agents, the first 60 shown.