copilot-extensions

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. A fifth plugin wraps authenticated MCP servers so those same host credentials reach your tools.

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

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). Standalone — used directly from an agent's `mcp-servers` config.
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.
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.
customizing-copilot	Customizing the CLI	Teach an agent how to customize and extend the Copilot CLI — authoring skills, defining sub-agents, registering MCP servers, and installing plugins (repo `settings.json`). Four focused skills. Payload-only — no runtime to install.

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

Architecture at a glance

Nine plugins, one marketplace. Six ship a runtime (a uv-built venv under ~/.agent-* + a ~/.local/bin binstub, deployed by the plugin's own installer); three are payload-only — efforts (skills), context-handoff (a session extension), and customizing-copilot (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"]
      AL["agent-logger<br/>session-sync + log writer"]
      PO["efforts · context-handoff · customizing-copilot<br/>(payload-only: skills / extension)"]
    end
    subgraph RT["Local runtimes — ~/.* + ~/.local/bin"]
      RW["~/.agent-worktrees<br/>agent-worktrees"]
      RB["~/.agent-bridge<br/>service :9280 Win / :9281 WSL"]
      RC["~/.agent-codespaces<br/>agent-codespaces"]
      RN["~/.agent-containers<br/>agent-containers"]
      RM["~/.agent-mcp<br/>agent-mcp"]
      RL["~/.agent-logger<br/>session-sync task + digests"]
    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| AL
    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
    AL -->|install.ps1 / install.sh| RL
    AC -.->|codespace resolver + relay| RB
    AN -.->|container resolver| 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 :9857"]
      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. The bridge installer imports agent-codespaces and agent-containers for their codespace: / container: resolvers, so install those before agent-bridge.

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 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 six runtime plugins (everything except efforts, context-handoff, and customizing-copilot) 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 copilot-extensions-setup § 0 and install-contract.md.

2. Bootstrap the runtimes

Start a Copilot CLI session and say "set up copilot extensions" — the 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

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 codespaces.yaml (Codespace defaults + credential-relay policy) 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.)

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 9857)
    Bridge->>Space: spawn copilot --acp over SSH
    Space-->>CS: git / gh credential request to :9857
    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
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

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 four 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

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 609 Commits
.agent-worktrees		.agent-worktrees
.github/plugin		.github/plugin
docs		docs
libs		libs
plugins		plugins
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

copilot-extensions

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

Agent Logger

Context Handoff

Customizing Copilot

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

copilot-extensions

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

Agent Logger

Context Handoff

Customizing Copilot

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages