drvoss 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.
- Research: Copilot investigates the codebase, dependencies, and current behavior
- Plan: Copilot proposes an implementation approach before writing code
- Review: You refine or approve the approach on GitHub
- 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:
/resumeis 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.
/resumefor 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.