copilot-multi-agent

Install one coordinated set of custom agents for VS Code and GitHub Copilot CLI. copilot-multi-agent bundles the multi-agent orchestration toolkit with automatic mode selection plus explicit cross-verification, complementary synthesis, task decomposition, and bounded iterative refinement launchers.

Requirements

• A current VS Code release with GitHub Copilot Chat.
• An active GitHub Copilot subscription and access to the configured worker models.
• PowerShell 7.4 or newer available as pwsh on the extension host.
• Python 3.10 or newer only when the optional local runtime is enabled.

Before an install, update, force update, or install preview starts, the extension checks the selected extension host. Missing GitHub Copilot Chat or PowerShell 7.4+ opens a prerequisite warning with Open Requirements and Retry actions; the installer script is not started and no user assets are changed. On the first install, missing Python 3.10+ is shown separately as an optional-runtime warning and Continue Install remains available. Python is not required for the Markdown agents or core asset installation.

Install the agents

Installing the extension does not silently modify the user profile. Run copilot-multi-agent: Install or Update User Assets from the Command Palette for the complete first-time flow: it installs or updates the shared assets and, when needed, opens GitHub Device Flow for the mandatory account check. GitHub still requires you to approve the one-time code in the browser.

The installer writes one shared agent copy to ~/.copilot/agents/. Current VS Code and GitHub Copilot CLI both discover that location, so no second CLI installation is required. Start a new chat or reload the VS Code window after installation.

Updates

VS Code updates the extension bundle through the Marketplace. The extension then prompts before synchronizing updated agents, skills, runtime files, schemas, and helpers into ~/.copilot.

The multiAgent.updateBehavior setting supports:

• prompt, the default, asks once for each extension version.
• automatic synchronizes after an extension install or update.
• manual disables automatic checks and prompts.

The hash-bound installer updates only files it owns and that remain unchanged. Modified or unowned files at managed paths fail closed. copilot-multi-agent: Force Update User Assets is available only as an explicit, confirmed action.

Commands

• copilot-multi-agent: Install or Update User Assets installs or updates all shared assets and starts the required GitHub account connection when needed.
• copilot-multi-agent: Preview User Asset Installation validates without writing.
• copilot-multi-agent: Force Update User Assets explicitly restores bundled content at known managed paths.
• copilot-multi-agent: Manage Subagents opens installed files for direct editing and supports creating or deleting custom read-only workers plus recreating and resetting builtin workers.
• copilot-multi-agent: Manage Modes directly edits builtin mode files, manages each builtin provider and launcher as one lifecycle group, and creates provider-only custom modes.
• copilot-multi-agent: Manage Runtime configures the optional runtime and checkpointing, shows runtime/Python/policy status, and opens the active user policy.
• copilot-multi-agent: Show Installation Status reports the current bundle and synchronization state.
• copilot-multi-agent: Connect GitHub Account opens the bounded Device Flow helper in a terminal.
• copilot-multi-agent: Preview User Asset Removal validates without writing.
• copilot-multi-agent: Uninstall User Assets removes only hash-owned managed files and preserves modified files and user state.
• copilot-multi-agent: Show Extension Output opens detailed local operation output.

Run the user-asset uninstall command before removing the extension when the agents should not remain installed.

Management commands affect only this extension's user-level files under ~/.copilot/agents/. They never edit workspace .github/agents/ files or unrelated user agents. Authentication, registry, evaluator, usage, metrics, telemetry, and runtime safety agents remain outside the management surface. At least one builtin worker and one builtin mode must remain installed.

Edit Original opens the installed Agent file itself; there is no replacement-file picker. Saves for each file are serialized. Each save must keep the canonical name, and its exact digest is stored as a user-approved override without changing the first-party trust manifest. Invalid saves remain unapproved until corrected and saved again. Workers cannot gain effectful tools, providers remain hidden and tool-free, and builtin launchers remain limited to the agent tool.

Custom definitions are tracked separately as user-owned content. A new worker uses the safe read-only worker template. A new mode creates one hidden provider for automatic discovery and no incomplete launcher. Install, Force Update, and uninstall preserve custom definitions; Delete Custom removes their files and exact approvals. Hash-matched builtin overrides survive normal extension updates; Reset, builtin Delete, Force Update, and forced uninstall remove only matching builtin override state and approval. Other active policy content remains unchanged.

Manage Runtime writes only runtime.enabled and runtime.checkpointing in the active user policy and preserves every other policy field. When no active policy exists, it creates one from the installed policy.example.json. Checkpointing cannot be enabled without Runtime, and Runtime enablement requires installed runtime files plus Python 3.10 or newer. Invalid or concurrently modified policy files are preserved and opened for manual correction.

Local and remote extension hosts

The extension runs only as a workspace extension. A local window targets the local machine. In Remote SSH, WSL, and development-container windows, install the extension on that remote workspace host; prerequisite checks and asset installation then target the same remote environment and home directory where VS Code and Copilot CLI should discover the agents.

Container-local files can disappear during rebuilds unless the home directory is persisted. For team-owned repository installations, keep the agent definitions in the workspace .github/agents/ directory instead of adding a duplicate user copy.

Security and privacy

Installer and uninstaller operations execute the bundled PowerShell files directly without a shell command string. Installation uses a closed path inventory, reparse-point checks, atomic file replacement, root-bound ownership metadata, per-file SHA-256 digests, and a digest-bound optional Python runtime launcher.

The extension never receives GitHub credentials. Account connection runs in a dedicated PowerShell terminal. Active policy, active telemetry configuration, credentials, queued telemetry, runtime state, locally modified files, and unknown files remain outside normal extension updates and removal.

Remote telemetry delivery is never activated by installing the extension. Local collection follows the bundled project policy, while authentication and scheduler registration remain separate explicit actions.