feat: add GitHub Copilot agent target

Signed-off-by: Sertan Helvacı <sertanhelvaci@icloud.com>

Author: sertanhelvaci

README.md

@@ -88,7 +88,8 @@ ships the same local engine inside the editor, still account-free:
 - right-click any file or folder → **Pathrule** → browse the knowledge an AI session there
   would receive, or scope a new memory/rule/skill in two keystrokes;
 - **Connect AI Clients**: GitHub Copilot agent mode registers automatically; Claude Code,
-  Cursor, Codex and Windsurf get managed MCP entries plus context hooks, no JSON editing;
+  Cursor, Codex, Windsurf and the Copilot CLI get managed MCP entries plus context hooks
+  (Copilot reads them from `.github/hooks/`), no JSON editing;
 - works on the same `~/.pathrule` store as the CLI: one identity, one knowledge base.
 
 Also on [Open VSX](https://open-vsx.org/extension/pathrule/pathrule-vscode) for Cursor and Windsurf.

packages/cli-local/src/install-local.ts

@@ -7,7 +7,7 @@
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
-import { getInstaller } from "@pathrule/shared/mcp-installers/registry.js";
+import { getInstallers } from "@pathrule/shared/mcp-installers/registry.js";
 import type { AgentTargetId } from "@pathrule/shared/skills/agent-targets.js";
 import type { McpServerEntry } from "@pathrule/shared/mcp-types.js";
 import { atomicWrite, readIfExists } from "@pathrule/shared/local-runtime/atomic-write.js";
@@ -36,9 +36,11 @@ const TARGET_ALIASES: Record<string, CliInstallTarget> = {
   cursor: "cursor",
   codex: "codex",
   windsurf: "windsurf",
+  copilot: "copilot",
+  "github-copilot": "copilot",
 };
 
-const ALL_TARGETS: AgentTargetId[] = ["claude-code", "cursor", "codex", "windsurf"];
+const ALL_TARGETS: AgentTargetId[] = ["claude-code", "cursor", "codex", "windsurf", "copilot"];
 
 export function parseInstallTargets(raw: string | undefined): AgentTargetId[] {
   const target = TARGET_ALIASES[(raw ?? "all").toLowerCase()];
@@ -68,32 +70,36 @@ export async function installEntryToCliTargets(
   env: NodeJS.ProcessEnv,
 ): Promise<CliInstallResult[]> {
   const platform = cliPlatform(env);
-  return Promise.all(
-    targets.map(async (target) => {
-      const installer = getInstaller(target);
-      const configPath = installer.homeConfigPath(homedir(), platform);
-      try {
-        const existing = await readIfExists(configPath);
-        const result = installer.inject(existing, entry);
-        await atomicWrite(configPath, result.body);
-        return {
-          client: target,
-          ok: true,
-          status: "installed" as const,
-          config_path: configPath,
-          was_new: result.wasNew,
-        };
-      } catch (err) {
-        return {
-          client: target,
-          ok: false,
-          status: "error" as const,
-          config_path: configPath,
-          error: err instanceof Error ? err.message : String(err),
-        };
-      }
-    }),
+  // One result per (target, config file) — multi-config clients (copilot:
+  // CLI config + VS Code user mcp.json) report each config separately.
+  const results = await Promise.all(
+    targets.flatMap((target) =>
+      getInstallers(target).map(async (installer): Promise<CliInstallResult> => {
+        const configPath = installer.homeConfigPath(homedir(), platform);
+        try {
+          const existing = await readIfExists(configPath);
+          const result = installer.inject(existing, entry);
+          await atomicWrite(configPath, result.body);
+          return {
+            client: target,
+            ok: true,
+            status: "installed" as const,
+            config_path: configPath,
+            was_new: result.wasNew,
+          };
+        } catch (err) {
+          return {
+            client: target,
+            ok: false,
+            status: "error" as const,
+            config_path: configPath,
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      }),
+    ),
   );
+  return results;
 }
 
 /**

packages/cli-local/src/local/setup-local.test.ts

@@ -17,13 +17,12 @@ vi.mock("@pathrule/shared/mcp-installers/registry.js", async (importOriginal) =>
     await importOriginal<typeof import("@pathrule/shared/mcp-installers/registry.js")>();
   return {
     ...actual,
-    getInstaller: (id: never) => {
-      const real = actual.getInstaller(id);
-      return {
+    getInstallers: (id: never) =>
+      actual.getInstallers(id).map((real, index) => ({
         ...real,
-        homeConfigPath: () => join(mocks.configDir.value, `${String(id)}.json`),
-      };
-    },
+        homeConfigPath: () =>
+          join(mocks.configDir.value, `${String(id)}${index > 0 ? `-${index}` : ""}.json`),
+      })),
   };
 });
 

packages/shared/src/hook-supervisor/client-config-writer.ts

@@ -1,6 +1,8 @@
 import {
   CLAUDE_TO_CODEX_EVENT_MAP,
   CLAUDE_TO_CODEX_TOOL_MAP,
+  CLAUDE_TO_COPILOT_EVENT_MAP,
+  CLAUDE_TO_COPILOT_TOOL_MAP,
   CLAUDE_TO_CURSOR_EVENT_MAP,
   CLAUDE_TO_CURSOR_TOOL_MAP,
 } from "./event-mapping.js";
@@ -155,3 +157,84 @@ export function buildCodexHookEvents(config: HookConfig): Record<string, HookMat
 export function renderCodexHooks(config: HookConfig): string {
   return `${JSON.stringify({ hooks: buildCodexHookEvents(config) }, null, 2)}\n`;
 }
+
+// ─── GitHub Copilot (docs.github.com/en/copilot/reference/hooks-configuration) ─
+// One `.github/hooks/pathrule.json` feeds all three Copilot surfaces: the CLI
+// reads it natively, VS Code agent mode converts the camelCase event names to
+// PascalCase, and the cloud coding agent reads `.github/hooks/*.json` as its
+// only hook source. Copilot's `matcher` is a regex anchored against the tool
+// name — Claude's `a|b|c` pipe lists are valid alternations as-is.
+
+const COPILOT_TOOL_SET = new Set(["bash", "create", "edit", "view", "grep", "glob"]);
+
+// VS Code agent mode uses its own tool names (docs show both naming
+// generations). Folded into matchers so PreToolUse/PostToolUse still fire if
+// a host applies the matcher against VS Code names rather than CLI names.
+const COPILOT_VSCODE_TOOL_ALIASES: Record<string, readonly string[]> = {
+  view: ["read_file", "readFile"],
+  edit: ["editFiles", "replace_string_in_file"],
+  create: ["createFile", "create_file"],
+  bash: ["runTerminalCommand", "run_in_terminal"],
+};
+
+const COPILOT_SUPPORTED_EVENTS = new Set<HookEventName>([
+  "SessionStart",
+  "PreToolUse",
+  "PostToolUse",
+  "Stop",
+  "SubagentStop",
+  "SessionEnd",
+]);
+
+/** One entry per hook in Copilot's flattened per-event array format. The env
+ *  stamp is the hook script's primary client discriminator; the event stamp
+ *  exists because Copilot CLI's camelCase payload carries no event name. */
+interface CopilotHookEntry {
+  type: "command";
+  command: string;
+  matcher?: string;
+  env: Record<string, string>;
+}
+
+function mapMatcherToCopilot(matcher: string | undefined): string | null | undefined {
+  if (!matcher) return undefined; // matcher-less entry — fires on every tool
+  const seen = new Set<string>();
+  const mapped: string[] = [];
+  for (const name of matcher.split("|")) {
+    const copilotName = CLAUDE_TO_COPILOT_TOOL_MAP[name];
+    if (!copilotName || !COPILOT_TOOL_SET.has(copilotName) || seen.has(copilotName)) continue;
+    seen.add(copilotName);
+    mapped.push(copilotName, ...(COPILOT_VSCODE_TOOL_ALIASES[copilotName] ?? []));
+  }
+  return mapped.length > 0 ? mapped.join("|") : null;
+}
+
+export function buildCopilotHookEvents(config: HookConfig): Record<string, CopilotHookEntry[]> {
+  const hooks: Record<string, CopilotHookEntry[]> = {};
+  for (const [rawEvent, rawMatchers] of Object.entries(config.hooks)) {
+    const event = rawEvent as HookEventName;
+    if (!COPILOT_SUPPORTED_EVENTS.has(event)) continue;
+    const copilotEvent = CLAUDE_TO_COPILOT_EVENT_MAP[event];
+    if (!copilotEvent || !rawMatchers || rawMatchers.length === 0) continue;
+    const entries: CopilotHookEntry[] = [];
+    for (const matcherGroup of rawMatchers) {
+      const matcher = mapMatcherToCopilot(matcherGroup.matcher);
+      if (matcher === null) continue; // every tool in the group is unmappable
+      for (const hook of matcherGroup.hooks) {
+        if (hook.type !== "command") continue;
+        entries.push({
+          type: "command",
+          command: hook.command,
+          ...(matcher !== undefined ? { matcher } : {}),
+          env: { PATHRULE_HOOK_CLIENT: "copilot", PATHRULE_HOOK_EVENT: copilotEvent },
+        });
+      }
+    }
+    if (entries.length > 0) hooks[copilotEvent] = entries;
+  }
+  return hooks;
+}
+
+export function renderCopilotHooks(config: HookConfig): string {
+  return `${JSON.stringify({ version: 1, hooks: buildCopilotHookEvents(config) }, null, 2)}\n`;
+}

packages/shared/src/hook-supervisor/event-mapping.ts

@@ -78,3 +78,51 @@ export const CLAUDE_TO_CODEX_TOOL_MAP: Record<string, string> = {
 export const CODEX_TO_CLAUDE_TOOL_MAP: Record<string, string> = {
   apply_patch: "Edit",
 };
+
+// ─── GitHub Copilot (docs.github.com/en/copilot/reference/hooks-configuration) ─
+// Copilot's native hook config uses camelCase event names; VS Code agent mode
+// converts them to PascalCase internally and the cloud coding agent reads the
+// same `.github/hooks/*.json` file. `UserPromptSubmit` is deliberately
+// unmapped: Copilot's userPromptSubmitted accepts no context output on any
+// surface, so wiring it would burn one process per prompt for zero injection
+// (same reasoning as Cursor's beforeSubmitPrompt).
+export type CopilotHookEventName =
+  | "sessionStart"
+  | "sessionEnd"
+  | "userPromptSubmitted"
+  | "preToolUse"
+  | "postToolUse"
+  | "postToolUseFailure"
+  | "agentStop"
+  | "subagentStart"
+  | "subagentStop"
+  | "errorOccurred"
+  | "preCompact"
+  | "permissionRequest"
+  | "notification";
+
+export const CLAUDE_TO_COPILOT_EVENT_MAP: Record<HookEventName, CopilotHookEventName | null> = {
+  PreToolUse: "preToolUse",
+  PostToolUse: "postToolUse",
+  UserPromptSubmit: null,
+  SessionStart: "sessionStart",
+  SessionEnd: "sessionEnd",
+  Stop: "agentStop",
+  SubagentStop: "subagentStop",
+  Notification: null,
+  PreCompact: null,
+  PostCompact: null,
+};
+
+// Copilot CLI + cloud coding agent tool names. VS Code agent mode uses its own
+// names (createFile/editFiles/runTerminalCommand…) handled by the hook
+// script's copilot branch; renderer matchers carry both via
+// COPILOT_VSCODE_TOOL_ALIASES in client-config-writer.ts.
+export const CLAUDE_TO_COPILOT_TOOL_MAP: Record<string, string> = {
+  Read: "view",
+  Edit: "edit",
+  Write: "create",
+  Bash: "bash",
+  Grep: "grep",
+  Glob: "glob",
+};

packages/shared/src/mcp-installers/copilot-installer.ts

@@ -0,0 +1,66 @@
+// GitHub Copilot MCP installers. Copilot is the one multi-config client: the
+// Copilot CLI reads `~/.copilot/mcp-config.json` while Copilot in VS Code
+// (agent mode without the Pathrule extension's McpServerDefinitionProvider)
+// reads the user-profile `mcp.json`. Both are registered under the single
+// `copilot` agent target; the registry returns them as an array and every
+// consumer iterates. The cloud coding agent's MCP config lives in repo
+// settings on github.com (no file or API to manage) — doctor surfaces it as
+// a documented manual step instead.
+//
+// Schemas verified in docs/superpowers/specs/m55-copilot-capability-spike.md.
+
+import {
+  defaultManagedEntryInfo,
+  joinHomePath,
+  type ClientInstaller,
+  type ManagedMcpEntryInfo,
+} from "./types.js";
+import { makeJsonInstaller } from "./json-installer.js";
+
+// Copilot CLI entry schema: `{ "type": "local", "command", "args", "env",
+// "tools": ["*"] }` under a `mcpServers` root. `tools` is the per-server
+// allowlist — `["*"]` enables every Pathrule tool.
+const cliJson = makeJsonInstaller({
+  includeTypeField: true,
+  typeFieldValue: "local",
+  entryExtras: { tools: ["*"] },
+});
+
+export const copilotCliInstaller: ClientInstaller = {
+  id: "copilot",
+  configLabel: "Copilot CLI",
+  homeConfigPath(homedir: string, platform: NodeJS.Platform): string {
+    return joinHomePath(platform, homedir, ".copilot", "mcp-config.json");
+  },
+  inject: cliJson.inject,
+  remove: cliJson.remove,
+  read: cliJson.read,
+  getManagedEntry(existing: string | null): ManagedMcpEntryInfo {
+    return defaultManagedEntryInfo(cliJson.read, existing);
+  },
+};
+
+// VS Code user-profile `mcp.json`: root key is `servers` (NOT `mcpServers`)
+// and the entry keeps `type: "stdio"`. Stable VS Code only in v1 —
+// Insiders/VSCodium profile variants are documented out of scope.
+const vscodeJson = makeJsonInstaller({ includeTypeField: true, rootKey: "servers" });
+
+export const copilotVscodeInstaller: ClientInstaller = {
+  id: "copilot",
+  configLabel: "VS Code user config",
+  homeConfigPath(homedir: string, platform: NodeJS.Platform): string {
+    if (platform === "darwin") {
+      return joinHomePath(platform, homedir, "Library", "Application Support", "Code", "User", "mcp.json");
+    }
+    if (platform === "win32") {
+      return joinHomePath(platform, homedir, "AppData", "Roaming", "Code", "User", "mcp.json");
+    }
+    return joinHomePath(platform, homedir, ".config", "Code", "User", "mcp.json");
+  },
+  inject: vscodeJson.inject,
+  remove: vscodeJson.remove,
+  read: vscodeJson.read,
+  getManagedEntry(existing: string | null): ManagedMcpEntryInfo {
+    return defaultManagedEntryInfo(vscodeJson.read, existing);
+  },
+};