copilot-extensions

The Worktree Picker — the front door to your fleet of worktree-backed agents, at a glance across every machine.

A Copilot CLI plugin suite that gives every session its own isolated git worktree and lets your agents talk to each other — across worktrees, across machines, and into GitHub Codespaces and local dev containers — with credentials forwarded securely along the way. The agent-mcp plugin wraps authenticated MCP servers so those same host credentials reach your tools.

Plugins, one marketplace. Install what you need; they compose.

Quick start — one-line setup

Bootstrap a machine into a working harness with the standalone Configurator — an out-of-plugin app that installs the prerequisites and the core, then adopts your first repo (it must run before the plugins do, so it is delivered outside the plugin pipe):

Windows (PowerShell):

iex (irm https://raw.githubusercontent.com/ThomasMichon/copilot-extensions/main/configurator/bootstrap.ps1)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/ThomasMichon/copilot-extensions/main/configurator/bootstrap.sh | bash

See configurator/. (Building out under #352 — a Phase 0 skeleton today; prerequisite install + core install land next.)

Plugin	Type	What it gives you
agent-worktrees	Session tool	Each Copilot CLI session runs in its own git worktree — no branch conflicts, no stale state. Install this first.
agent-bridge	Persistent service	Send prompts to agents on other machines (or other worktrees) over an always-on local service + SSH mesh.
agent-codespaces	CLI + relay	Create/manage GitHub Codespaces, address them as bridge agents (`codespace:<name>`), and forward git/GitHub/Azure credentials into them.
agent-containers	CLI + resolver	Manage a fleet of local Docker dev containers, borrow/release them per effort, and address them as bridge agents (`container:<name>`).
agent-mcp	MCP bridge	Wrap an upstream MCP server (HTTP or stdio) as a local stdio MCP and inject host credentials (Entra/`az`, `gh`, git-credential, env). Dual-era: speaks modern MCP 2.x (`2026-07-28`) and the legacy handshake. Standalone — used directly from an agent's `mcp-servers` config.
agent-ssh	SSH connectivity CLI	Emit and verify machine-name SSH profiles from a normalized registry, and define the public transport-provider contract for direct or tunnel transports.
efforts	Planning skills	Plan a stretch of work as an effort — a folder with a README-as-shared-contract (premise + plan + journal) that humans and agents coordinate through. The executor plugins above bind its participant seam.
visions	Planning skills	Keep a persistent vision — a north-star statement of what a system should ultimately be — and derive efforts from the delta between vision and reality. Payload-only — no runtime to install.
agent-logger	Session logging	Turn raw Copilot sessions into structured Markdown logs — a segmenter, a voice-neutral log-writer agent, and a `session-sync` step that pushes session data to a configurable target (local / OneDrive / SSH / ingest). Personality is injected by the host, never built in.
context-handoff	Extension + skill	Watch the context window via a session extension and, before it fills, compose a continuation prompt so a fresh session can resume the work. Payload-only — no runtime to install.
agent-dispatch	Task queue + coordinator	Coordinate multiple agents through a single-writer leased task queue (atomic claim, capability routing, lease recovery) instead of racing through `origin/master` pushes. Per-host coordinator, CLI, and MCP tools.
agent-index	Index/search service	Portable indexing and semantic-search engine for a harness repo and its immediate ecosystem. Phase 1 ships the service shell; indexing and retrieval arrive in later slices.
agent-machines	Machine-state reconciler	Portable restore-machinestate — converge a machine to desired state declared in in-repo requirement packages (Copilot settings first). Machine-scoped union restore, a seven-disposition model, and a detect-not-arbitrate conflict validator. The engine is generic; sensitive OS-mutating modules stay repo-local.
agent-vault	CLI + service	Local KeePassXC-backed secret store — a machine-local service caches the master password with a TTL and auto-prompts on lock; a CLI fetches API keys, SSH keys, and credentials on demand without hardcoding, committing, or env-exporting them. Ships a SUDO_ASKPASS helper for `sudo -A`.
customizing-copilot	Customizing the CLI	Teach an agent how to customize and extend the Copilot CLI — authoring skills, defining sub-agents, registering MCP servers, installing plugins, building a control-harness, reviewing customizations, and authoring `<repo>-harness` plugins. Seven focused skills. Payload-only — no runtime to install.
copilot-extensions-harness	Operator harness	The portable, owner-authored skills to work on this suite — contribute changes and diagnose the deployed runtimes. Enable it in any control repo instead of hand-writing a per-repo narrative. Reference implementation of the `<repo>-harness` standard. Payload-only.
wsl-setup	Environment setup	Set up and troubleshoot WSL2 as a reachable, persistent service host — pick the networking mode (NAT + localhostForwarding vs mirrored), diagnose corp-network egress + host↔WSL loopback failures, and keep a distro alive for a hosted listener (e.g. sshd behind a Dev Tunnel). Ships a windowless keepalive helper.
harness-knowledge	Binding skill	Bind a stateless control harness to its private knowledge repo, harness-first — ask for (or create) the knowledge repo, write the machine-local `knowledge_repo` pointer, and assemble a machine-local instructions fragment labeling the concrete harness/knowledge/product paths. Keeps the shareable harness tree generic + name-free. Payload-only.

All support Windows and Linux/WSL (macOS planned).

Architecture at a glance

Eighteen plugins, one marketplace. Eleven ship a runtime (a uv-built venv under ~/.agent-* + a ~/.local/bin binstub, deployed by the plugin's own installer); seven are payload-only — efforts (skills), visions (skills), context-handoff (a session extension), customizing-copilot (skills), copilot-extensions-harness (skills), wsl-setup (skills), and harness-knowledge (skills) need no install beyond enabling the plugin. Everything installs from the marketplace and runs from local install paths — no git checkout required at runtime.

flowchart TB
    MP["GitHub marketplace<br/>ThomasMichon/copilot-extensions"]
    subgraph IP["~/.copilot/installed-plugins/copilot-extensions/"]
      AW["agent-worktrees<br/>skills + sessionStart hook"]
      AB["agent-bridge<br/>service source + libs/ssh-manager"]
      AC["agent-codespaces<br/>CLI + credential relay"]
      AN["agent-containers<br/>CLI + container: resolver"]
      AM["agent-mcp<br/>MCP bridge CLI"]
      AS["agent-ssh<br/>SSH profile CLI"]
      AL["agent-logger<br/>session-sync + log writer"]
      AD["agent-dispatch<br/>task-queue service + CLI"]
      AI["agent-index<br/>index/search service"]
      AK["agent-machines<br/>machine-state reconciler CLI"]
      AV["agent-vault<br/>secret store CLI + service"]
      PO["efforts · visions · context-handoff · customizing-copilot<br/>copilot-extensions-harness · wsl-setup · harness-knowledge<br/>(payload-only: skills / extension)"]
    end
    subgraph RT["Local runtimes — ~/.* + ~/.local/bin"]
      RW["~/.agent-worktrees<br/>agent-worktrees"]
      RB["~/.agent-bridge<br/>service (OS-assigned port)"]
      RC["~/.agent-codespaces<br/>agent-codespaces"]
      RN["~/.agent-containers<br/>agent-containers"]
      RM["~/.agent-mcp<br/>agent-mcp"]
      RS["~/.agent-ssh<br/>agent-ssh"]
      RL["~/.agent-logger<br/>session-sync task + digests"]
      RD["~/.agent-dispatch<br/>queue db + coordinator"]
      RI["~/.agent-index<br/>service + engine"]
      RK["~/.agent-machines<br/>reconciler"]
      RV["~/.agent-vault<br/>secret store service"]
    end
    MP -->|copilot plugin install| AW
    MP -->|copilot plugin install| AB
    MP -->|copilot plugin install| AC
    MP -->|copilot plugin install| AN
    MP -->|copilot plugin install| AM
    MP -->|copilot plugin install| AS
    MP -->|copilot plugin install| AL
    MP -->|copilot plugin install| AD
    MP -->|copilot plugin install| AI
    MP -->|copilot plugin install| AK
    MP -->|copilot plugin install| AV
    MP -->|copilot plugin install| PO
    AW -->|init.ps1 / init.sh| RW
    AB -->|install.ps1 / install.sh| RB
    AC -->|init.ps1 / init.sh| RC
    AN -->|init.ps1 / init.sh| RN
    AM -->|init.ps1 / init.sh| RM
    AS -->|install.ps1 / install.sh| RS
    AL -->|install.ps1 / install.sh| RL
    AD -->|install.ps1 / install.sh| RD
    AI -->|install.ps1 / install.sh| RI
    AK -->|install.ps1 / install.sh| RK
    AV -->|install.ps1 / install.sh| RV
    AC -.->|codespace: provider via providers.d/ manifest| RB
    AN -.->|container: provider via providers.d/ manifest| RB

Each runtime plugin is itself a Python package (its src/ plus vendored libs/); the installer creates the venv with uv venv and installs the package with uv pip install <plugin_dir>. See Quick Start and Architecture overview for the payload-vs-runtime split.

How the pieces relate at run time:

flowchart LR
    subgraph Yours["Your machine"]
      direction TB
      CLI["Copilot CLI session"]
      WT["agent-worktrees<br/>per-session worktree"]
      BR["agent-bridge<br/>service"]
      CS["agent-codespaces<br/>+ credential relay"]
      CN["agent-containers<br/>local dev-container fleet"]
      MCP["agent-mcp<br/>MCP bridge (host creds)"]
      CLI --> WT
      CLI -->|agent-bridge send| BR
      CLI -.->|mcp-servers: agent-mcp| MCP
      BR --> CS
      BR --> CN
    end
    BR -->|SSH| OM["Other machines<br/>dev box, WSL, server"]
    CS -->|SSH + gh| GH["GitHub Codespaces"]
    CS -.->|forwards git / gh / az creds| GH
    CN -->|docker exec| DC["Local dev containers"]
    CN -.->|forwards gh token| DC

Quick Start

Goal: from a fresh machine to "send a prompt to my CodeSpace and get work done" in a handful of steps. New to this? Read Concepts first.

Prerequisites

Copilot CLI (copilot on PATH) · Python 3.10+ · Git 2.15+
gh CLI, authenticated (gh auth login) — for agent-codespaces and agent-containers
Docker (Docker Desktop WSL2 backend) — for agent-containers only
uv (bootstrapped automatically by the init scripts if missing)

1. Install the plugins

Install agent-worktrees first; add the others as you need them. agent-codespaces and agent-containers self-register their codespace: / container: namespaces with agent-bridge by dropping a ~/.agent-bridge/providers.d/ manifest on session start — there is no install-order requirement and no package import, so a provider installed at any time is discovered on demand.

copilot plugin marketplace add ThomasMichon/copilot-extensions
copilot plugin install agent-worktrees@copilot-extensions
copilot plugin install agent-codespaces@copilot-extensions
copilot plugin install agent-containers@copilot-extensions
copilot plugin install agent-bridge@copilot-extensions
copilot plugin install agent-mcp@copilot-extensions      # optional, standalone
copilot plugin install agent-logger@copilot-extensions   # optional — session logging
copilot plugin install agent-index@copilot-extensions    # optional — indexing/search service shell
copilot plugin install efforts@copilot-extensions        # optional — planning skills (no runtime)
copilot plugin install context-handoff@copilot-extensions # optional — context-window handoff (no runtime)
copilot plugin install customizing-copilot@copilot-extensions # optional — how to customize the CLI (no runtime)

Each copilot plugin install only vendors the plugin's payload (source, skills, hooks, extensions). The eleven runtime plugins (every plugin except the payload-only efforts, visions, context-handoff, customizing-copilot, copilot-extensions-harness, and wsl-setup) then need their runtime deployed once — that's Step 2, which runs each installer to build a uv venv under ~/.agent-* and drop a binstub in ~/.local/bin.

Recommended: register at repo scope instead of globally. Set "experimental": true in ~/.copilot/settings.json, then declare the marketplace + enabledPlugins in your control repo's committed .github/copilot/settings.json. Copilot vendors the payloads when a session runs in that repo (agent-worktrees may need a session restart to take effect), Step 2 deploys the runtimes, and every subsequent launch via the binstub/terminal profile runs agent-worktrees reconcile-plugins to keep the payloads and runtimes fresh automatically. See agent-worktrees:copilot-extensions-setup § 0 and install-contract.md.

2. Bootstrap the runtimes

Start a Copilot CLI session and say "set up copilot extensions" — the agent-worktrees:copilot-extensions-setup skill runs each installer so the runtimes land under ~/.agent-* with binstubs in ~/.local/bin. (Prefer to do it by hand? See each plugin's Getting Started, linked below.)

Verify:

agent-worktrees --version
agent-bridge version && agent-bridge status
agent-codespaces version
agent-ssh version

3. Adopt your control-harness repo

Adopt your control repo (see Concepts) so worktrees, topology, and Codespaces all read from one place:

cd /path/to/my-control-harness
agent-worktrees register my-control-harness          # worktree sessions + binstub
agent-bridge config adopt --repo . --profile my-control-harness
agent-codespaces config adopt

4. First send — local, then CodeSpace

# Talk to a local agent (no SSH needed)
agent-bridge send local "Print the working directory and git branch."

# Talk to a CodeSpace through the bridge (auto-starts it; creds forwarded)
agent-codespaces bridge register
agent-bridge send "codespace:<name>" "Run: pwd && git rev-parse --abbrev-ref HEAD && gh auth status"

Concepts: the control-harness repo

A control-harness repo is your own repo (a dotfiles-style "hub") that drives the whole system. In examples it's called my-control-harness. It:

is adopted by agent-worktrees (gets a project binstub + worktree root),
holds the topology the bridge reads — machines.yaml (machines + SSH) and acp-agents.json (agents), plus a supplementary .agent-codespaces/config.yaml (Codespace overrides + credential-relay policy; most repos need none) and containers.yaml (local dev-container fleet defaults), and
doubles as the Codespaces dotfiles repo, so the same repo provisions each CodeSpace.

One repo, one source of truth, the mesh plugins reading from it. (agent-mcp is standalone — its bridge configs are per-agent files, preferably in-repo via --config for repo-scoped agents, or under ~/.agent-mcp/bridges/ for personal ones; not the control repo.)

Building or auditing a harness? Point an agent at the Control-Harness Runbook — an opinionated, phase-by-phase procedure for turning a repo into an effective agent harness with these plugins. It works from a fresh folder ("make me a control repo like this"), on an existing repo ("build out my harness"), or as an audit ("make sure my repo follows best practices").

Usage flow: a CodeSpace session end-to-end

sequenceDiagram
    participant You as Copilot CLI
    participant Bridge as agent-bridge
    participant CS as agent-codespaces
    participant Space as CodeSpace
    You->>Bridge: agent-bridge send "codespace:my-space" "..."
    Bridge->>CS: resolve codespace:my-space
    CS->>Space: gh codespace start (if Shutdown) + SSH (-R to the relay port)
    Bridge->>Space: spawn copilot --acp over SSH
    Space-->>CS: git / gh credential request to the local relay
    CS-->>Space: token (from GCM / gh auth)
    Space-->>Bridge: streamed response
    Bridge-->>You: response

The credential relay (port 9857) means the CodeSpace authenticates to GitHub and Azure DevOps using your host's credentials — no PATs baked into the CodeSpace.

Updating

# Pull the latest plugin from the marketplace…
copilot plugin update agent-worktrees@copilot-extensions

# …or update the plugin + runtime in one step
agent-worktrees update

agent-worktrees also auto-updates its runtime on session launch. agent-bridge and agent-codespaces update via their installers (scripts/install.* update). agent-containers and agent-mcp re-run their scripts/init.* (with -Force / --force) to redeploy the runtime.

Uninstalling / baseline reset

The installer-based plugins (agent-worktrees, agent-bridge, agent-codespaces) provide an uninstall action that stops their own managed processes before removing files — agent-bridge stops the daemon + credential relay, and agent-codespaces closes its SSH ControlMaster connections — so no manual process-killing is needed:

scripts/install.sh uninstall          # per-plugin (add --purge / --remove-config to wipe config)

agent-containers and agent-mcp are init-only (no installer): remove them by deleting ~/.agent-containers / ~/.agent-mcp and their ~/.local/bin binstubs.

To return a machine to a clean baseline in one step (stops everything, removes the installer-based runtimes, binstubs, the service/scheduled task, and config) use the repo-level reset tool — it's idempotent and works even if the CLIs are broken:

# Windows
pwsh -File tools\reset.ps1                       # prompts; add -Yes to skip
pwsh -File tools\reset.ps1 -Yes -RemovePlugins   # also `copilot plugin uninstall`

# Linux/WSL
bash tools/reset.sh                              # prompts; add --yes to skip
bash tools/reset.sh --yes --remove-plugins

The reset tool currently targets the installer-based runtimes (~/.agent-worktrees, ~/.agent-bridge, ~/.agent-codespaces); remove ~/.agent-containers and ~/.agent-mcp manually until it covers them.

Your source repos and their .worktrees content are never touched.

Documentation

Guides & component breakdowns

Document	What's inside
Control-Harness Runbook	Opinionated, phase-by-phase procedure for building/extending/auditing an agent harness with these plugins
Plugin consolidation	Discussion: whether to collapse the multi-plugin suite into fewer plugins, with decision criteria
Architecture overview	How the plugins fit together: install topology, runtimes, ports, credential relay
Rollout plan	Onboarding-readiness plan and fixes
Fresh dev box validation	Step-by-step validation on a clean machine

Agent Worktrees

Document	Description
README	Plugin overview
Getting Started	Install, adopt a repo, launch sessions
Architecture	Plugin/runtime layers, session lifecycle
CLI Reference	Commands, installer actions, config format

Agent Bridge

Document	Description
README	Plugin overview
Getting Started	Install, configure, start the service
Architecture	Service design, API reference, deployment
Machine Configuration	Topology — `machines.yaml`, `acp-agents.json`

Agent Codespaces

Document	Description
README	Plugin overview, CLI reference, config format
codespaces-setup	First-time setup, adoption, credential relay config
codespaces-lifecycle	Day-to-day ops — SSH, listing, bridge integration

Agent Containers

Document	Description
README	Plugin overview, CLI reference, config format, discovery
containers-fleet	Fleet provisioning, borrow/release leases, `container:` dispatch

Agent MCP

Document	Description
README	Plugin overview, bridge config format, auth kinds, CLI
agent-mcp	Defining a bridge, wiring it into an agent's `mcp-servers`

Efforts

Document	Description
README	Plugin overview, the skill-governs-pattern + repo-addendum model
planning-efforts	Start, plan, resume, archive efforts
reference guide	Full effort schema, lifecycle, participants seam
efforts-setup	Adopt efforts in a repo: scaffold + write the addendum

Visions

Document	Description
README	Plugin overview, the north-star model, skill-governs + repo-addendum
envisioning	Create/revise a vision, derive the delta into efforts
visions-setup	Adopt visions in a repo: scaffold + write the addendum

Agent Logger

Document	Description
README	Plugin overview, pipeline pieces, design principles
log-session	Write a log for one session on demand
process-backlog	Batch-log a backlog of unlogged sessions locally
session-sync-setup	Configure + deploy session-sync (target, schedule)

Context Handoff

Document	Description
README	Plugin overview, why an extension, no-install delivery
context-handoff	The `/handoff` continuation-prompt workflow
context-handoff-setup	Enable the plugin extension in a repo

Customizing Copilot

Document	Description
README	Plugin overview, the seven skills, no-install delivery
authoring-skills	SKILL.md format, folder convention, validation, hooks, custom instructions
defining-subagents	Custom agents: `.agent.md`, tool aliases, MCP ownership, anti-recursion
registering-mcp-servers	MCP registration hierarchy, config formats, writing a server
installing-plugins	Repo `settings.json` registration, experimental mode, payload-vs-runtime
building-harnesses	In-session entry to the Control-Harness Runbook (greenfield / brownfield / audit)
reviewing-customizations	Review a harness's skills, sub-agents, `AGENTS.md`, hooks, MCP configs
authoring-harness-plugins	The `<repo>-harness` standard: ship operator skills for a repo

Agent Dispatch

Document	Description
README	Plugin overview, the leased queue engine, coordinator, CLI, MCP tools

Agent Vault

Document	Description
README	Plugin overview, the local vault service, CLI verbs, SUDO_ASKPASS
agent-vault	Day-to-day: store/fetch secrets, SSH keys, fetch-on-demand discipline
agent-vault-setup	Install/update the runtime, first-run DB config, SUDO_ASKPASS wiring

Harness (copilot-extensions)

Document	Description
README	Operator harness overview + the `<repo>-harness` standard
contributing-to-copilot-extensions	Change + land work in a plugin: flow, the mandatory version bump, gates, deploy
diagnosing-copilot-extensions	Symptom → cause → action for deployed plugins, key paths, baseline reset

Contributing

Document	Description
CONTRIBUTING	Versioning, release workflow, deployment pipeline
AGENTS	Repo development guide

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1,871 Commits
.agent-worktrees		.agent-worktrees
.github		.github
docs		docs
efforts/active/agent-index-engine-daemon		efforts/active/agent-index-engine-daemon
libs		libs
plugins		plugins
tools		tools
visions		visions
worktree-manager		worktree-manager
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md

Navigation Menu

Repository files navigation

copilot-extensions

Quick start — one-line setup

Architecture at a glance

Quick Start

Prerequisites

1. Install the plugins

2. Bootstrap the runtimes

3. Adopt your control-harness repo

4. First send — local, then CodeSpace

Concepts: the control-harness repo

Usage flow: a CodeSpace session end-to-end

Updating

Uninstalling / baseline reset

Documentation

Guides & component breakdowns

Agent Worktrees

Agent Bridge

Agent Codespaces

Agent Containers

Agent MCP

Efforts

Visions

Agent Logger

Context Handoff

Customizing Copilot

Agent Dispatch

Agent Vault

Harness (copilot-extensions)

Contributing

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

copilot-extensions

Quick start — one-line setup

Architecture at a glance

Quick Start

Prerequisites

1. Install the plugins

2. Bootstrap the runtimes

3. Adopt your control-harness repo

4. First send — local, then CodeSpace

Concepts: the control-harness repo

Usage flow: a CodeSpace session end-to-end

Updating

Uninstalling / baseline reset

Documentation

Guides & component breakdowns

Agent Worktrees

Agent Bridge

Agent Codespaces

Agent Containers

Agent MCP

Efforts

Visions

Agent Logger

Context Handoff

Customizing Copilot

Agent Dispatch

Agent Vault

Harness (copilot-extensions)

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages