Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat: support GitHub Copilot CLI (#2640)

mike-inkeep50534fb8bae8
diff --git a/.changeset/add-copilot-cli.md b/.changeset/add-copilot-cli.md
new file mode 100644
index 000000000..ff1d5ebc8
--- /dev/null
+++ b/.changeset/add-copilot-cli.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Add GitHub Copilot CLI integration with MCP, skills, and terminal launching.
diff --git a/docs/content/integrations/github-copilot-cli.mdx b/docs/content/integrations/github-copilot-cli.mdx
new file mode 100644
index 000000000..5ffe4780f
--- /dev/null
+++ b/docs/content/integrations/github-copilot-cli.mdx
@@ -0,0 +1,29 @@
+---
+title: GitHub Copilot CLI
+description: Use OpenKnowledge with GitHub Copilot CLI.
+icon: custom/GitHub
+---
+
+OpenKnowledge plugs into GitHub Copilot CLI through MCP.
+
+## Install
+
+<McpInstall editor="GitHub Copilot CLI" />
+
+`ok init` writes the MCP server to `~/.copilot/mcp-config.json`, or to `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set. The configuration is global because Copilot CLI prioritizes global MCP configuration over project configuration.
+
+If the Copilot config directory does not exist yet, launch Copilot CLI once and rerun `ok init` so it can write the MCP configuration.
+
+It also installs the project skill at `.github/skills/open-knowledge/SKILL.md` so Copilot can follow the project's OpenKnowledge workflow.
+
+## Open with AI
+
+In OpenKnowledge's docked terminal, select **GitHub Copilot** from the new-chat picker. It starts Copilot CLI in interactive mode with context for the current project. The option is hidden when the `copilot` executable is not installed.
+
+## Verify
+
+Open the project in GitHub Copilot CLI and ask:
+
+<VerifyExec subject="GitHub Copilot CLI" />
+
+If you don't see the tool, restart Copilot CLI. If `ok init` reported that your config was left unchanged, fix the reported config issue and rerun `ok init`. To add it manually, create an `open-knowledge` entry in `mcpServers` that runs `ok mcp`.
diff --git a/docs/content/integrations/meta.json b/docs/content/integrations/meta.json
index 193ff7f25..896c4363a 100644
--- a/docs/content/integrations/meta.json
+++ b/docs/content/integrations/meta.json
@@ -5,6 +5,7 @@
"claude-code",
"cursor",
"codex",
+ "github-copilot-cli",
"opencode",
"pi",
"openclaw",
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index 1438951c7..448ab6a3f 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -88,9 +88,9 @@ When you initialize or open a project, the app scaffolds the same project files
| `.okignore` | Paths excluded from the editor, search, and agents — see [Ignore patterns](/docs/features/ignore-patterns) | In-project, committed |
| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration for the four MCP-capable project editors (Claude, Cursor, Codex, OpenCode), written regardless of what's installed so the repo is ready for teammates | In-project, committed |
| `.pi/extensions/open-knowledge.ts` | Managed bridge extension connecting [Pi](/docs/integrations/pi) (which has no MCP support) to the project | In-project, committed |
-| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for the same five editors | In-project, committed |
+| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for Claude, Cursor, Codex, GitHub Copilot, OpenCode, and Pi | In-project, committed |
| `.ok/skill-targets.json` | Committed list of which editors receive skills, written when you customize the targets | In-project, committed |
-| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json`, `~/.openclaw/openclaw.json`, `~/.gemini/config/mcp_config.json`, `~/.lmstudio/mcp.json`, `~/.hermes/config.yaml` | User-level `open-knowledge` MCP registration, one per detected editor, so it's available in every project (`~/.openclaw/openclaw.json` only when `~/.openclaw/` exists; `~/.gemini/config/mcp_config.json` is Antigravity's shared IDE + `agy` config, only when `~/.gemini/` exists; `~/.lmstudio/mcp.json` and `~/.hermes/config.yaml` only when those apps are installed) | Outside-project (editor config) |
+| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.copilot/mcp-config.json`, `~/.config/opencode/opencode.json`, `~/.openclaw/openclaw.json`, `~/.gemini/config/mcp_config.json`, `~/.lmstudio/mcp.json`, `~/.hermes/config.yaml` | User-level `open-knowledge` MCP registration, one per detected editor, so it's available in every project (`~/.copilot/mcp-config.json` only when `~/.copilot/` exists; `~/.openclaw/openclaw.json` only when `~/.openclaw/` exists; `~/.gemini/config/mcp_config.json` is Antigravity's shared IDE + `agy` config, only when `~/.gemini/` exists; `~/.lmstudio/mcp.json` and `~/.hermes/config.yaml` only when those apps are installed) | Outside-project (editor config) |
### While a project is open
@@ -165,7 +165,7 @@ The `postinstall` step is **non-fatal** (install always succeeds even if it fail
| `.gitignore` (project root) | Seeded (with `.DS_Store`) **only** when `ok init` creates a new git repo | In-project, committed |
| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration for the four MCP-capable project editors (Claude, Cursor, Codex, OpenCode) regardless of what's installed — prepares the repo for teammates (with `--scope project` or `both`) | In-project, committed |
| `.pi/extensions/open-knowledge.ts` | Managed bridge extension connecting [Pi](/docs/integrations/pi) (which has no MCP support) to the project | In-project, committed |
-| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for the same five editors | In-project, committed |
+| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for Claude, Cursor, Codex, GitHub Copilot, OpenCode, and Pi | In-project, committed |
| `.ok/skill-targets.json` | Committed list of which editors receive skills, written when you customize the targets | In-project, committed |
With `--scope user` or `both` (the default), `ok init` also registers the `open-knowledge` MCP server in each detected editor's **user-level** config, so it's available in every project:
@@ -176,6 +176,7 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-
| `~/Library/Application Support/Claude/claude_desktop_config.json` | Claude Desktop | Outside-project (editor config) |
| `~/.cursor/mcp.json` | Cursor | Outside-project (editor config) |
| `~/.codex/config.toml` | Codex | Outside-project (editor config) |
+| `~/.copilot/mcp-config.json` | GitHub Copilot CLI (only when `~/.copilot/` exists; respects `COPILOT_HOME`) | Outside-project (editor config) |
| `~/.config/opencode/opencode.json` | OpenCode | Outside-project (editor config) |
| `~/.openclaw/openclaw.json` | OpenClaw (only when `~/.openclaw/` exists) | Outside-project (editor config) |
| `~/.gemini/config/mcp_config.json` | Antigravity (only when `~/.gemini/` exists) — shared by the IDE and the `agy` CLI | Outside-project (editor config) |
diff --git a/packages/app/src/components/ConsentDialogBody.dom.test.tsx b/packages/app/src/components/ConsentDialogBody.dom.test.tsx
index 4c2f40727..4303d61dd 100644
--- a/packages/app/src/components/ConsentDialogBody.dom.test.tsx
+++ b/packages/app/src/components/ConsentDialogBody.dom.test.tsx
@@ -208,7 +208,12 @@ describe('ConsentDialogBody runtime form behavior', () => {
return '/project/docs/notes';
},
},
- } as Pick<OkDesktopBridge, 'dialog'>);
+ onboarding: {
+ probeContent: async () => ({ ok: true, count: 0, sample: [], truncated: false }),
+ },
+ } satisfies Pick<OkDesktopBridge, 'dialog'> & {
+ onboarding: Pick<OkDesktopBridge['onboarding'], 'probeContent'>;
+ });
renderConsentDialog();
await expandAdvanced();
diff --git a/packages/app/src/components/DocumentErrorBoundary.dom.test.tsx b/packages/app/src/components/DocumentErrorBoundary.dom.test.tsx
index 5025ec823..d7e4ec4c1 100644
--- a/packages/app/src/components/DocumentErrorBoundary.dom.test.tsx
+++ b/packages/app/src/components/DocumentErrorBoundary.dom.test.tsx
@@ -247,8 +247,9 @@ describe('DocumentErrorBoundary (Tier-3 mount)', () => {
const user = userEvent.setup();
await user.click(screen.getByRole('button', { name: /report this error/i }));
- // ReportBugDialog is lazy-loaded — await the body chunk mounting.
- expect(await screen.findByRole('dialog')).not.toBeNull();
+ // ReportBugDialog is lazy-loaded. Its dynamic import can exceed Testing
+ // Library's one-second default under full-suite CI load.
+ expect(await screen.findByRole('dialog', undefined, { timeout: 5000 })).not.toBeNull();
expect(screen.getByRole('heading', { name: 'Report a bug' })).not.toBeNull();
const checkbox = screen.getByRole('checkbox', { name: 'Detailed diagnostics' });
expect(checkbox.getAttribute('aria-checked')).toBe('true');
diff --git a/packages/app/src/components/TerminalNewChatButton.dom.test.tsx b/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
index 231c5edba..e6c7842f6 100644
--- a/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
+++ b/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
@@ -50,13 +50,19 @@ describe('TerminalNewChatButton', () => {
expect(onPickTerminal).not.toHaveBeenCalled();
});
- test('the dropdown lists every CLI plus a Terminal option', async () => {
+ test('the dropdown lists every available CLI plus a Terminal option', async () => {
const user = userEvent.setup();
renderButton('claude');
await user.click(screen.getByRole('button', { name: 'Choose CLI for new chat' }));
- for (const name of ['Claude CLI', 'Codex CLI', 'OpenCode CLI', 'Cursor CLI']) {
+ for (const name of [
+ 'Claude CLI',
+ 'Codex CLI',
+ 'GitHub Copilot CLI',
+ 'OpenCode CLI',
+ 'Cursor CLI',
+ ]) {
expect(await screen.findByRole('menuitem', { name })).toBeDefined();
}
expect(screen.getByRole('menuitem', { name: 'Terminal' })).toBeDefined();
@@ -73,6 +79,7 @@ describe('TerminalNewChatButton', () => {
expect(await screen.findByRole('menuitem', { name: 'Claude CLI' })).toBeDefined();
expect(screen.getByRole('menuitem', { name: 'Codex CLI' })).toBeDefined();
+ expect(screen.queryByRole('menuitem', { name: 'GitHub Copilot CLI' })).toBeNull();
expect(screen.queryByRole('menuitem', { name: 'Antigravity CLI' })).toBeNull();
expect(screen.queryByRole('menuitem', { name: 'Cursor CLI' })).toBeNull();
// The bare-shell Terminal row is independent of CLI gating — always present.
diff --git a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
index f34606f67..0cd530c03 100644
--- a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
@@ -106,9 +106,12 @@ async function renderSubmenu({
const trigger = screen.getByRole('menuitem', { name: 'Open with AI' });
await userEvent.hover(trigger);
- await waitFor(() => {
- expect(document.querySelector('[data-slot="dropdown-menu-sub-content"]')).toBeTruthy();
- });
+ await waitFor(
+ () => {
+ expect(document.querySelector('[data-slot="dropdown-menu-sub-content"]')).toBeTruthy();
+ },
+ { timeout: 5000 },
+ );
return { dispatch, dispatchCalls, trigger };
}
diff --git a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
index 6e7f59959..94b8f5a02 100644
--- a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
@@ -112,9 +112,12 @@ async function renderSubmenu({
async function openEmptySpaceSubmenu() {
const trigger = screen.getByRole('menuitem', { name: 'Open with AI' });
await userEvent.hover(trigger);
- await waitFor(() => {
- expect(document.querySelector('[data-slot="context-menu-sub-content"]')).toBeTruthy();
- });
+ await waitFor(
+ () => {
+ expect(document.querySelector('[data-slot="context-menu-sub-content"]')).toBeTruthy();
+ },
+ { timeout: 5000 },
+ );
return trigger;
}
diff --git a/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx b/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx
index 7d60790c8..230d182a4 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx
@@ -37,6 +37,7 @@ import type { CSSProperties, ReactNode, SVGProps } from 'react';
import { AntigravityIcon } from '@/components/icons/antigravity';
import { ClaudeIcon } from '@/components/icons/claude';
import { CodexBrandIcon } from '@/components/icons/codex';
+import { CopilotIcon } from '@/components/icons/copilot';
import { CursorIcon } from '@/components/icons/cursor';
import { OpenCodeIcon } from '@/components/icons/opencode';
import { PiIcon } from '@/components/icons/pi';
@@ -69,6 +70,7 @@ const TARGET_ICON_KEY: Record<TargetData['id'], string> = {
'claude-code': 'claude',
codex: 'openai',
cursor: 'cursor',
+ copilot: 'github',
// No `AGENT_ICON_COLORS` entry → renders monochrome (inherits the row's text
// color), which suits OpenCode's, Pi's, and Antigravity's monochrome brand marks.
opencode: 'opencode',
@@ -104,6 +106,8 @@ export function TargetIcon({
if (id === 'codex')
return <CodexBrandIcon style={mergedStyle} className={mergedClass} {...props} />;
if (id === 'cursor') return <CursorIcon style={mergedStyle} className={mergedClass} {...props} />;
+ if (id === 'copilot')
+ return <CopilotIcon style={mergedStyle} className={mergedClass} {...props} />;
if (id === 'opencode')
return <OpenCodeIcon style={mergedStyle} className={mergedClass} {...props} />;
if (id === 'pi') return <PiIcon style={mergedStyle} className={mergedClass} {...props} />;
diff --git a/packages/app/src/components/handoff/terminal-cli-display.test.ts b/packages/app/src/components/handoff/terminal-cli-display.test.ts
index b19825afb..b35ac3a44 100644
--- a/packages/app/src/components/handoff/terminal-cli-display.test.ts
+++ b/packages/app/src/components/handoff/terminal-cli-display.test.ts
@@ -23,6 +23,10 @@ describe('visibleTerminalClis', () => {
]);
});
+ it('hides GitHub Copilot when the probe confirms it is absent', () => {
+ expect(visibleTerminalClis({ ...allAbsent, copilot: false })).not.toContain('copilot');
+ });
+
it('always keeps Claude — the install-nudge anchor — even when probed absent', () => {
expect(visibleTerminalClis(allAbsent)).toEqual(['claude']);
});
diff --git a/packages/app/src/components/terminal-session-registry.test.ts b/packages/app/src/components/terminal-session-registry.test.ts
index d1119d7f8..244d178af 100644
--- a/packages/app/src/components/terminal-session-registry.test.ts
+++ b/packages/app/src/components/terminal-session-registry.test.ts
@@ -1,4 +1,5 @@
import { afterEach, describe, expect, test } from 'bun:test';
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
import {
_clearTerminalSessionRegistry,
findIdleMatchingSession,
@@ -14,7 +15,7 @@ afterEach(() => {
function register(
id: string,
- cli: 'claude' | 'codex' | 'cursor' | null,
+ cli: TerminalCli | null,
ptyId: string | null,
lastOutputAt: number,
hasOutput: boolean,
diff --git a/packages/app/src/lib/default-cli-resolver.test.ts b/packages/app/src/lib/default-cli-resolver.test.ts
index 1ae3540f9..b94f8e87f 100644
--- a/packages/app/src/lib/default-cli-resolver.test.ts
+++ b/packages/app/src/lib/default-cli-resolver.test.ts
@@ -6,7 +6,7 @@
* Resolution contract:
* 1. sticky parses to a CLI (via parseStickyCliId) → it, unconditionally
* (an explicit pick is honored even when the CLI is KNOWN-absent);
- * 2. else the first KNOWN-installed CLI by priority (claude > codex > opencode > cursor > pi);
+ * 2. else the first KNOWN-installed CLI by priority (claude > codex > opencode > cursor > copilot > pi);
* 3. else 'claude'.
*/
@@ -69,9 +69,11 @@ describe('resolveDefaultCli', () => {
expect(resolveDefaultCli(null, installedMap(['codex', 'opencode', 'cursor']))).toBe('codex');
});
- test('respects the full priority order claude > codex > opencode > cursor > pi', () => {
+ test('respects the full priority order claude > codex > opencode > cursor > copilot > pi', () => {
+ expect(resolveDefaultCli(null, installedMap(['copilot', 'opencode']))).toBe('opencode');
expect(resolveDefaultCli(null, installedMap(['opencode', 'cursor']))).toBe('opencode');
- expect(resolveDefaultCli(null, installedMap(['cursor', 'pi']))).toBe('cursor');
+ expect(resolveDefaultCli(null, installedMap(['cursor', 'copilot']))).toBe('cursor');
+ expect(resolveDefaultCli(null, installedMap(['copilot', 'pi']))).toBe('copilot');
expect(resolveDefaultCli(null, installedMap(['pi']))).toBe('pi');
expect(resolveDefaultCli(null, installedMap(['claude', 'codex', 'opencode', 'cursor']))).toBe(
'claude',
diff --git a/packages/app/src/lib/default-cli-resolver.ts b/packages/app/src/lib/default-cli-resolver.ts
index 1a4bb261b..dd7b6a44b 100644
--- a/packages/app/src/lib/default-cli-resolver.ts
+++ b/packages/app/src/lib/default-cli-resolver.ts
@@ -7,7 +7,7 @@
* (a `HandoffTarget` id, e.g. `claude-code`) is intentionally ignored here —
* `parseStickyCliId` returns `null` for it and resolution falls through to the
* installed-priority auto-pick. Priority order is `TERMINAL_CLI_IDS` itself
- * (claude > codex > opencode > cursor > pi); reusing it keeps the auto-pick order in
+ * (claude > codex > opencode > cursor > copilot > pi); reusing it keeps the auto-pick order in
* lockstep with the visible launch-row order rather than duplicating a list.
*/
diff --git a/packages/app/src/lib/handoff/dispatch.test.ts b/packages/app/src/lib/handoff/dispatch.test.ts
index 65ada0533..9d1fc7fc9 100644
--- a/packages/app/src/lib/handoff/dispatch.test.ts
+++ b/packages/app/src/lib/handoff/dispatch.test.ts
@@ -176,6 +176,7 @@ describe('dispatchHandoff — runtime exhaustiveness guard', () => {
});
test.each([
+ 'copilot',
'opencode',
'pi',
'antigravity',
diff --git a/packages/app/src/lib/handoff/dispatch.ts b/packages/app/src/lib/handoff/dispatch.ts
index b1a2a41bf..c6b28988e 100644
--- a/packages/app/src/lib/handoff/dispatch.ts
+++ b/packages/app/src/lib/handoff/dispatch.ts
@@ -116,6 +116,14 @@ export async function dispatchHandoff(
},
fetchImpl,
);
+ case 'copilot':
+ // Terminal-only target: Copilot has no desktop URL transport and is
+ // launched through `requestTerminalLaunch`, never this deep-link path.
+ return {
+ ok: false,
+ reason: 'invalid-payload',
+ detail: 'copilot is terminal-only; launch via requestTerminalLaunch',
+ };
case 'opencode':
// Terminal-only target: OpenCode has no URL scheme and is launched via
// `requestTerminalLaunch` (the terminal-CLI path), never the deep-link
diff --git a/packages/app/src/lib/handoff/targets.test.ts b/packages/app/src/lib/handoff/targets.test.ts
index 3fe9e1a24..302fff933 100644
--- a/packages/app/src/lib/handoff/targets.test.ts
+++ b/packages/app/src/lib/handoff/targets.test.ts
@@ -2,18 +2,29 @@ import { describe, expect, test } from 'bun:test';
import { KNOWN_TARGETS, VISIBLE_TARGETS } from './targets.ts';
describe('KNOWN_TARGETS', () => {
- test('has exactly seven targets (four GUI + terminal-only OpenCode, Pi, Antigravity)', () => {
- expect(KNOWN_TARGETS.length).toBe(7);
+ test('has exactly eight targets (four GUI + terminal-only Copilot, OpenCode, Pi, Antigravity)', () => {
+ expect(KNOWN_TARGETS.length).toBe(8);
});
test('ids cover the full HandoffTarget union', () => {
const ids = new Set(KNOWN_TARGETS.map((t) => t.id));
expect(ids).toEqual(
- new Set(['claude-cowork', 'claude-code', 'codex', 'cursor', 'opencode', 'pi', 'antigravity']),
+ new Set([
+ 'claude-cowork',
+ 'claude-code',
+ 'codex',
+ 'cursor',
+ 'copilot',
+ 'opencode',
+ 'pi',
+ 'antigravity',
+ ]),
);
});
- test('opencode, pi, and antigravity are terminal-only — no URL scheme', () => {
+ test('copilot, opencode, pi, and antigravity are terminal-only — no URL scheme', () => {
+ const copilot = KNOWN_TARGETS.find((t) => t.id === 'copilot');
+ expect(copilot?.schemes).toEqual([]);
const opencode = KNOWN_TARGETS.find((t) => t.id === 'opencode');
expect(opencode?.schemes).toEqual([]);
const pi = KNOWN_TARGETS.find((t) => t.id === 'pi');
@@ -48,6 +59,7 @@ describe('KNOWN_TARGETS', () => {
expect(byId.get('claude-code')).toBe('Claude');
expect(byId.get('codex')).toBe('Codex');
expect(byId.get('cursor')).toBe('Cursor');
+ expect(byId.get('copilot')).toBe('GitHub Copilot');
expect(byId.get('opencode')).toBe('OpenCode');
expect(byId.get('pi')).toBe('Pi');
expect(byId.get('antigravity')).toBe('Antigravity');
@@ -65,11 +77,12 @@ describe('VISIBLE_TARGETS (UI render allow-list)', () => {
expect(ids.has('claude-cowork')).toBe(false);
});
- test('hides the terminal-only opencode + pi + antigravity targets from the GUI deep-link list', () => {
- // OpenCode, Pi, and Antigravity surface as terminal-CLI launch rows
+ test('hides the terminal-only copilot + opencode + pi + antigravity targets from the GUI deep-link list', () => {
+ // Copilot, OpenCode, Pi, and Antigravity surface as terminal-CLI launch rows
// (TERMINAL_CLI_IDS), not GUI deep-link targets, so they must not appear in
// VISIBLE_TARGETS.
const ids = new Set(VISIBLE_TARGETS.map((t) => t.id));
+ expect(ids.has('copilot')).toBe(false);
expect(ids.has('opencode')).toBe(false);
expect(ids.has('pi')).toBe(false);
expect(ids.has('antigravity')).toBe(false);
diff --git a/packages/app/src/lib/handoff/targets.ts b/packages/app/src/lib/handoff/targets.ts
index 5495b35a1..61f954db2 100644
--- a/packages/app/src/lib/handoff/targets.ts
+++ b/packages/app/src/lib/handoff/targets.ts
@@ -51,6 +51,14 @@ export const KNOWN_TARGETS = [
installUrl: 'https://cursor.com/',
tagline: 'AI-first VS Code fork with multi-file edits.',
},
+ {
+ // Terminal-only target, reached via the `copilot` CLI launch row.
+ id: 'copilot',
+ displayName: 'GitHub Copilot',
+ schemes: [],
+ installUrl: 'https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-getting-started',
+ tagline: "GitHub's terminal-native coding agent.",
+ },
{
// Terminal-only target: no URL scheme (empty `schemes`), so it is never
// deep-link-dispatched (no `dispatch.ts` URL case, no `RECIPES` recipe) nor
@@ -90,11 +98,12 @@ export const KNOWN_TARGETS = [
// group, and the empty-state "Create with <agent>" composer.
export const VISIBLE_TARGETS: ReadonlyArray<TargetData> = KNOWN_TARGETS.filter(
// `claude-cowork`: dispatch-by-ID only, no render surface.
- // `opencode` / `pi` / `antigravity`: terminal-only — surfaced via the
+ // `copilot` / `opencode` / `pi` / `antigravity`: terminal-only — surfaced via the
// terminal-CLI rows, not the GUI deep-link target list, so they must not
// appear as dispatchable rows.
(target) =>
target.id !== 'claude-cowork' &&
+ target.id !== 'copilot' &&
target.id !== 'opencode' &&
target.id !== 'pi' &&
target.id !== 'antigravity',
diff --git a/packages/app/src/lib/unified-agent-store.test.ts b/packages/app/src/lib/unified-agent-store.test.ts
index d497d3216..a149a21e0 100644
--- a/packages/app/src/lib/unified-agent-store.test.ts
+++ b/packages/app/src/lib/unified-agent-store.test.ts
@@ -6,7 +6,11 @@
*/
import { describe, expect, test } from 'bun:test';
-import type { HandoffTarget, InstallState } from '@inkeep/open-knowledge-core';
+import {
+ type HandoffTarget,
+ type InstallState,
+ TERMINAL_CLI_IDS,
+} from '@inkeep/open-knowledge-core';
import {
loadStickyAgent,
parseStickyCliId,
@@ -121,7 +125,7 @@ describe('unified-agent-store — resolveStickyAgent', () => {
describe('terminalCliId / parseStickyCliId', () => {
test('round-trips each CLI through the per-CLI sentinel', () => {
- for (const cli of ['claude', 'codex', 'cursor'] as const) {
+ for (const cli of TERMINAL_CLI_IDS) {
expect(parseStickyCliId(terminalCliId(cli))).toBe(cli);
}
});
diff --git a/packages/app/tests/integration/_fixtures/init-load-byte-stable-snapshot.ts b/packages/app/tests/integration/_fixtures/init-load-byte-stable-snapshot.ts
index fac76235b..2fef600b9 100644
--- a/packages/app/tests/integration/_fixtures/init-load-byte-stable-snapshot.ts
+++ b/packages/app/tests/integration/_fixtures/init-load-byte-stable-snapshot.ts
@@ -32,7 +32,7 @@ export function sha256(buf: Buffer): string {
* `.ok/` (init artifact), `.git/` (git metadata), `node_modules/`, and the
* editor / agent tool dirs: `ok init` installs the project-local skill into
* every configured editor's skills root (`.claude/skills/`, `.cursor/skills/`,
- * `.codex/skills/`, `.opencode/skills/`, `.pi/skills/`, plus the generic
+ * `.codex/skills/`, `.github/skills/`, `.opencode/skills/`, `.pi/skills/`, plus the generic
* `.agents/skills/`).
* Those SKILL.md files are tool-config artifacts, not user knowledge-base
* content — the load-without-mutate property is about user `.md` / `.mdx`
@@ -47,6 +47,7 @@ const SNAPSHOT_EXCLUDED_DIRS = new Set([
'.claude',
'.cursor',
'.codex',
+ '.github',
'.opencode',
'.pi',
'.agents',
diff --git a/packages/app/tests/stress/fixtures/handoff-mocks.ts b/packages/app/tests/stress/fixtures/handoff-mocks.ts
index 089b590d6..7e0ede041 100644
--- a/packages/app/tests/stress/fixtures/handoff-mocks.ts
+++ b/packages/app/tests/stress/fixtures/handoff-mocks.ts
@@ -603,6 +603,7 @@ export async function installHandoffMocks(page: Page, cfg: HandoffMockConfig): P
cliInstalledMap: async () => ({
claude: true,
codex: true,
+ copilot: true,
opencode: true,
cursor: true,
pi: true,
diff --git a/packages/cli/src/commands/editors.test.ts b/packages/cli/src/commands/editors.test.ts
index c40cfa42f..e050efc52 100644
--- a/packages/cli/src/commands/editors.test.ts
+++ b/packages/cli/src/commands/editors.test.ts
@@ -17,6 +17,7 @@ import {
resolveClaudeCodeConfigPath,
resolveClaudeDesktopConfigPath,
resolveCodexConfigPath,
+ resolveCopilotConfigPath,
resolveCursorConfigPath,
resolveEditorTargets,
resolveHermesConfigPath,
@@ -154,6 +155,24 @@ describe('resolveCodexConfigPath', () => {
});
});
+describe('resolveCopilotConfigPath', () => {
+ it('builds the default Copilot CLI MCP path', () => {
+ expect(
+ resolveCopilotConfigPath({ home: '/Users/alice', platformName: 'darwin', env: {} }),
+ ).toBe('/Users/alice/.copilot/mcp-config.json');
+ });
+
+ it('honors COPILOT_HOME when present', () => {
+ expect(
+ resolveCopilotConfigPath({
+ home: '/Users/alice',
+ platformName: 'darwin',
+ env: { COPILOT_HOME: '/tmp/custom-copilot-home' },
+ }),
+ ).toBe('/tmp/custom-copilot-home/mcp-config.json');
+ });
+});
+
describe('resolveOpenCodeConfigPath', () => {
it('builds the XDG default on Linux', () => {
expect(resolveOpenCodeConfigPath({ home: '/home/alice', platformName: 'linux', env: {} })).toBe(
@@ -316,6 +335,35 @@ describe('EDITOR_TARGETS.pi', () => {
});
});
+describe('EDITOR_TARGETS.copilot', () => {
+ const t = EDITOR_TARGETS.copilot;
+
+ it('writes the managed launcher into Copilot CLI’s user-global mcpServers file', () => {
+ expect(t.format).toBe('json');
+ expect(t.topLevelKey).toBe('mcpServers');
+ expect(t.scope).toBe('global');
+ expect(t.configPath('', '/Users/alice')).toBe('/Users/alice/.copilot/mcp-config.json');
+ expect(t.detectPath?.('', '/Users/alice')).toBe('/Users/alice/.copilot');
+ expect(t.projectConfigPath).toBeUndefined();
+ expect(t.projectSkillPath?.('/proj')).toBe('/proj/.github/skills/open-knowledge/SKILL.md');
+ });
+
+ it('uses COPILOT_HOME for both config and installation detection', () => {
+ const previous = process.env.COPILOT_HOME;
+ try {
+ process.env.COPILOT_HOME = '/tmp/custom-copilot-home';
+ expect(t.configPath('', '/Users/alice')).toBe('/tmp/custom-copilot-home/mcp-config.json');
+ expect(t.detectPath?.('', '/Users/alice')).toBe('/tmp/custom-copilot-home');
+ } finally {
+ if (previous === undefined) {
+ delete process.env.COPILOT_HOME;
+ } else {
+ process.env.COPILOT_HOME = previous;
+ }
+ }
+ });
+});
+
describe('EDITOR_TARGETS.openclaw', () => {
it('nests the managed launcher under mcp.servers', () => {
const t = EDITOR_TARGETS.openclaw;
@@ -459,6 +507,7 @@ describe('buildManagedServerEntry', () => {
'claude-desktop',
'cursor',
'codex',
+ 'copilot',
'openclaw',
'antigravity',
];
@@ -764,6 +813,7 @@ describe('buildManagedServerEntry (win32)', () => {
'claude-desktop',
'cursor',
'codex',
+ 'copilot',
'openclaw',
'antigravity',
];
diff --git a/packages/cli/src/commands/editors.ts b/packages/cli/src/commands/editors.ts
index 3d82a4044..bd5eca842 100644
--- a/packages/cli/src/commands/editors.ts
+++ b/packages/cli/src/commands/editors.ts
@@ -260,6 +260,8 @@ export interface McpInstallOptions {
* never sets it.
*/
skipAvailabilityCheck?: boolean;
+ /** Override the user home used by cross-scope integration prerequisites. */
+ home?: string;
}
/**
@@ -574,6 +576,19 @@ export function resolveCodexConfigPath(options: AppSupportOptions = {}): string
return pathApiForPlatform(platformName).join(resolveCodexHomePath(options), 'config.toml');
}
+/**
+ * GitHub Copilot CLI keeps user-global MCP configuration under `COPILOT_HOME`
+ * (default `~/.copilot`). Its standard JSON `mcpServers` envelope is compatible
+ * with the managed launcher used by Claude and Cursor.
+ */
+export function resolveCopilotConfigPath(options: AppSupportOptions = {}): string {
+ const platformName = options.platformName ?? process.platform;
+ const home = options.home ?? homedir();
+ const env = options.env ?? process.env;
+ const copilotHome = env.COPILOT_HOME ?? pathApiForPlatform(platformName).join(home, '.copilot');
+ return pathApiForPlatform(platformName).join(copilotHome, 'mcp-config.json');
+}
+
/**
* OpenCode follows the XDG base-dir convention on every platform: its global
* config lives at `$XDG_CONFIG_HOME/opencode/` (default `~/.config/opencode/`),
@@ -803,6 +818,22 @@ export const EDITOR_TARGETS: Record<EditorId, EditorMcpTarget> = {
// `.agents/skills/` as a generic store, but OK writes the primary dir.
projectSkillPath: (cwd) => join(cwd, '.codex', 'skills', 'open-knowledge', 'SKILL.md'),
},
+ copilot: {
+ id: 'copilot',
+ label: EDITOR_LABELS.copilot,
+ configPath: (_cwd, home) => resolveCopilotConfigPath({ home }),
+ format: 'json',
+ topLevelKey: 'mcpServers',
+ serverName: () => MCP_SERVER_NAME,
+ buildEntry: (_cwd, options) => buildManagedServerEntry(options),
+ scope: 'global',
+ detectPath: (_cwd, home) => dirname(resolveCopilotConfigPath({ home })),
+ // Copilot's project skills use the GitHub-standard `.github/skills` root.
+ // Its MCP config remains user-global: duplicating the `open-knowledge`
+ // server into the shared workspace `.mcp.json` would leave two same-named
+ // sources for Copilot to reconcile.
+ projectSkillPath: (cwd) => join(cwd, '.github', 'skills', 'open-knowledge', 'SKILL.md'),
+ },
opencode: {
id: 'opencode',
label: EDITOR_LABELS.opencode,
diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts
index 40c7562b1..aa459aa73 100644
--- a/packages/cli/src/commands/init.test.ts
+++ b/packages/cli/src/commands/init.test.ts
@@ -700,6 +700,7 @@ describe('runInit', () => {
mkdirSync(dirname(resolveClaudeDesktopConfigPath({ home: fakeHome })), { recursive: true });
mkdirSync(dirname(cursorConfigPath()), { recursive: true });
mkdirSync(dirname(codexConfigPath()), { recursive: true });
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
mkdirSync(dirname(opencodeConfigPath()), { recursive: true });
mkdirSync(join(fakeHome, '.openclaw'), { recursive: true });
mkdirSync(join(fakeHome, '.pi', 'agent'), { recursive: true });
@@ -726,6 +727,7 @@ describe('runInit', () => {
expect(existsSync(resolveClaudeDesktopConfigPath({ home: fakeHome }))).toBe(true);
expect(existsSync(cursorConfigPath())).toBe(true);
expect(existsSync(codexConfigPath())).toBe(true);
+ expect(existsSync(join(fakeHome, '.copilot', 'mcp-config.json'))).toBe(true);
expect(existsSync(opencodeConfigPath())).toBe(true);
expect(existsSync(lmStudioConfigPath())).toBe(true);
// OpenClaw nests under `mcp.servers` — verify the entry landed there.
@@ -1315,6 +1317,101 @@ describe('runInit', () => {
);
});
+ it('wires Copilot’s user-global MCP config and project-local GitHub skill', async () => {
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
+ const result = await runInitForTest({ editors: ['copilot'], scope: 'user' });
+
+ expect(result.editors).toEqual([
+ expect.objectContaining({
+ editorId: 'copilot',
+ action: 'written',
+ configPath: join(fakeHome, '.copilot', 'mcp-config.json'),
+ }),
+ ]);
+ expect(existsSync(join(fakeHome, '.copilot', 'mcp-config.json'))).toBe(true);
+ expect(existsSync(join(testDir, '.mcp.json'))).toBe(false);
+ expect(result.projectSkills).toContainEqual(
+ expect.objectContaining({
+ editorId: 'copilot',
+ action: 'written',
+ path: join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'),
+ }),
+ );
+ });
+
+ it('includes Copilot’s project skill in the default detected-editor run', async () => {
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
+ const result = await runInitForTest({ scope: 'user' });
+
+ expect(result.projectSkills).toContainEqual(
+ expect.objectContaining({
+ editorId: 'copilot',
+ action: 'written',
+ path: join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'),
+ }),
+ );
+ });
+
+ it('does not install Copilot’s project skill when its MCP config is skipped', async () => {
+ const result = await runInitForTest({ editors: ['copilot'], mcp: false });
+
+ expect(result.editors[0]).toMatchObject({
+ editorId: 'copilot',
+ action: 'skipped-flag',
+ });
+ expect(result.projectSkills).toContainEqual(
+ expect.objectContaining({
+ editorId: 'copilot',
+ action: 'skipped-prerequisite',
+ }),
+ );
+ expect(existsSync(join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(
+ false,
+ );
+ });
+
+ it('installs Copilot’s project skill with custom pre-existing MCP wiring', async () => {
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
+ writeFileSync(
+ join(fakeHome, '.copilot', 'mcp-config.json'),
+ JSON.stringify({
+ mcpServers: {
+ 'open-knowledge': { command: 'custom-ok', args: ['mcp'] },
+ },
+ }),
+ );
+
+ const result = await runInitForTest({ editors: ['copilot'], mcp: false });
+
+ expect(result.projectSkills).toContainEqual(
+ expect.objectContaining({ editorId: 'copilot', action: 'written' }),
+ );
+ expect(existsSync(join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(
+ true,
+ );
+ });
+
+ it('does not install Copilot’s project skill when its MCP config write is declined', async () => {
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
+ writeFileSync(join(fakeHome, '.copilot', 'mcp-config.json'), '{ "mcpServers": ');
+
+ const result = await runInitForTest({ editors: ['copilot'], scope: 'user' });
+
+ expect(result.editors[0]).toMatchObject({
+ editorId: 'copilot',
+ action: 'declined',
+ });
+ expect(result.projectSkills).toContainEqual(
+ expect.objectContaining({
+ editorId: 'copilot',
+ action: 'skipped-prerequisite',
+ }),
+ );
+ expect(existsSync(join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(
+ false,
+ );
+ });
+
it('scope=project writes only project-level config for Claude', async () => {
const result = await runInitForTest({ editors: ['claude'], scope: 'project' });
// Only the project-scope result
@@ -1387,6 +1484,25 @@ describe('runInit', () => {
expect(result.editors).toHaveLength(0);
});
+ it('scope=project skips Copilot’s skill because it cannot establish MCP wiring', async () => {
+ const result = await runInitForTest({ editors: ['copilot'], scope: 'project' });
+
+ expect(result.editors).toHaveLength(0);
+ expect(result.projectSkills).toContainEqual(
+ expect.objectContaining({
+ editorId: 'copilot',
+ action: 'skipped-prerequisite',
+ path: join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'),
+ }),
+ );
+ expect(existsSync(join(testDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(
+ false,
+ );
+ expect(formatInitResult(result, testDir)).not.toContain(
+ 'GitHub Copilot does not support project-level config; skipped',
+ );
+ });
+
it('scope=both writes user-level AND project-level for claude', async () => {
const result = await runInitForTest({ editors: ['claude'], scope: 'both' });
expect(result.editors).toHaveLength(2);
@@ -2032,6 +2148,7 @@ describe('detectInstalledEditors', () => {
const originalPlatform = process.platform;
const originalHome = process.env.HOME;
const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+ const originalCopilotHome = process.env.COPILOT_HOME;
const cursorConfigPath = () => resolveCursorConfigPath({ home: fakeHome });
const codexConfigPath = () => resolveCodexConfigPath({ home: fakeHome, env: {} });
@@ -2048,6 +2165,7 @@ describe('detectInstalledEditors', () => {
mkdirSync(fakeHome, { recursive: true });
process.env.HOME = fakeHome;
delete process.env.XDG_CONFIG_HOME;
+ delete process.env.COPILOT_HOME;
Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
});
@@ -2066,6 +2184,11 @@ describe('detectInstalledEditors', () => {
} else {
process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
}
+ if (originalCopilotHome === undefined) {
+ delete process.env.COPILOT_HOME;
+ } else {
+ process.env.COPILOT_HOME = originalCopilotHome;
+ }
rmSync(testDir, { recursive: true, force: true });
});
@@ -2110,6 +2233,15 @@ describe('detectInstalledEditors', () => {
expect(detected).toContain('codex');
});
+ it('detects Copilot when ~/.copilot exists', async () => {
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
+ expect(detectInstalledEditors(testDir, fakeHome)).toContain('copilot');
+ });
+
+ it('does NOT detect Copilot when ~/.copilot is absent', async () => {
+ expect(detectInstalledEditors(testDir, fakeHome)).not.toContain('copilot');
+ });
+
it('detects Claude Desktop when its config directory exists', async () => {
mkdirSync(dirname(resolveClaudeDesktopConfigPath({ home: fakeHome })), { recursive: true });
const detected = detectInstalledEditors(testDir, fakeHome);
@@ -2126,6 +2258,7 @@ describe('detectInstalledEditors', () => {
mkdirSync(dirname(resolveClaudeDesktopConfigPath({ home: fakeHome })), { recursive: true });
mkdirSync(dirname(cursorConfigPath()), { recursive: true });
mkdirSync(dirname(codexConfigPath()), { recursive: true });
+ mkdirSync(join(fakeHome, '.copilot'), { recursive: true });
mkdirSync(dirname(opencodeConfigPath()), { recursive: true });
mkdirSync(join(fakeHome, '.openclaw'), { recursive: true });
mkdirSync(join(fakeHome, '.pi', 'agent'), { recursive: true });
@@ -2152,7 +2285,8 @@ describe('detectInstalledEditors', () => {
mkdirSync(dirname(cursorConfigPath()), { recursive: true });
mkdirSync(dirname(codexConfigPath()), { recursive: true });
const detected = detectInstalledEditors(testDir, fakeHome);
- // Order comes from ALL_EDITOR_IDS = ['claude', 'claude-desktop', 'cursor', 'codex']
+ // These are the only configured roots in this fixture, so their order follows
+ // the corresponding prefix of ALL_EDITOR_IDS.
expect(detected).toEqual(['claude', 'claude-desktop', 'cursor', 'codex']);
});
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index c84b3a829..4e3f91323 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -8,7 +8,8 @@
* config file. The CLI owns the `open-knowledge` / `open-knowledge-ui`
* entries and rewrites them to the current defaults on every run.
*
- * Supports Claude, Claude Desktop, Cursor, Codex, and OpenCode.
+ * Supports Claude, Claude Desktop, Cursor, Codex, GitHub Copilot, OpenCode,
+ * and other registered MCP hosts.
* Missing editor config roots are skipped so init does not create new user-home
* directories for tools that are not installed.
*/
@@ -1669,12 +1670,17 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
// 2. Wire MCP config per editor (unless --no-mcp). Defaults are scope-aware:
// user-level writes stay limited to editors detected on this machine, while
- // project-level writes create all standardized project config files so a repo
- // can be prepared for teammates who use different editors.
+ // project-level targets include every host with either a config or a skill
+ // surface. That lets a global-MCP host such as Copilot receive its project
+ // skill without duplicating its server into a shared workspace config.
const userEditorIds = options.editors ?? detectInstalledEditors(projectRoot, options.home);
const projectEditorIds =
options.editors ??
- ALL_EDITOR_IDS.filter((id) => EDITOR_TARGETS[id].projectConfigPath !== undefined);
+ ALL_EDITOR_IDS.filter(
+ (id) =>
+ EDITOR_TARGETS[id].projectConfigPath !== undefined ||
+ EDITOR_TARGETS[id].projectSkillPath !== undefined,
+ );
const userTargets = resolveEditorTargets(userEditorIds as EditorId[]);
const projectTargets = resolveEditorTargets(projectEditorIds as EditorId[]);
const skipMcp = options.mcp === false || scope === null;
@@ -1750,13 +1756,16 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
const skillPath = target.projectSkillPath?.(projectRoot);
if (!skillPath || writtenSkillPaths.has(skillPath)) continue;
writtenSkillPaths.add(skillPath);
- projectSkillResults.push(writeProjectSkill(target, projectRoot));
+ projectSkillResults.push(writeProjectSkill(target, projectRoot, { home: options.home }));
}
- // Editors skipped for project-scope because they have no project-local config format.
+ // Editors skipped for project-scope because they have no project-local artifact.
+ // Copilot has no project MCP-config format, but it does receive a project skill.
const projectScopeUnsupportedLabels =
!skipMcp && scope !== null && writesProject(scope)
- ? projectTargets.filter((t) => !t.projectConfigPath).map((t) => t.label)
+ ? projectTargets
+ .filter((t) => !t.projectConfigPath && !t.projectSkillPath)
+ .map((t) => t.label)
: undefined;
const legacyProjectConfigs = skipMcp
@@ -2126,6 +2135,9 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string
case 'skipped-unsupported':
lines.push(` ${label}${pad}no known project skill surface; skipped`);
break;
+ case 'skipped-prerequisite':
+ lines.push(` ${label}${pad}OpenKnowledge MCP is not configured; skipped`);
+ break;
case 'failed':
lines.push(` ${label}${pad}${displayPath} ${error('FAILED')}: ${skill.error}`);
break;
diff --git a/packages/cli/src/commands/repair-skills.test.ts b/packages/cli/src/commands/repair-skills.test.ts
index 1f311c781..e04003845 100644
--- a/packages/cli/src/commands/repair-skills.test.ts
+++ b/packages/cli/src/commands/repair-skills.test.ts
@@ -979,12 +979,13 @@ describe('repairSkills — OK_RECLAIM_DISABLE env gate (AC-C1)', () => {
describe('coverage meta-test (AC-D2): HOSTS_WITH_USER_SKILL_DIR ↔ EDITOR_TARGETS.projectSkillPath', () => {
it('CLI host list matches the set of editor ids that declare a projectSkillPath', () => {
- // Pi is the documented carve-out: it declares a projectSkillPath
- // (`.pi/skills`) but has NO `~/.pi/skills` user dir — its user-global
- // skills live at `~/.pi/agent/skills` and it reads the central
- // `~/.agents/skills` hub natively, so the user host-dir sweep skips it.
+ // Pi and Copilot are documented carve-outs: their project skill paths do
+ // not imply the `~/.<host>/skills` shape used by this user host-dir sweep.
+ // Both read the central `~/.agents/skills` hub natively.
const hostsWithProjectSkillPath = Object.entries(EDITOR_TARGETS)
- .filter(([id, target]) => target.projectSkillPath !== undefined && id !== 'pi')
+ .filter(
+ ([id, target]) => target.projectSkillPath !== undefined && id !== 'pi' && id !== 'copilot',
+ )
.map(([id]) => id)
.sort();
diff --git a/packages/cli/src/integrations/project-integration-writers.test.ts b/packages/cli/src/integrations/project-integration-writers.test.ts
index 9ad5411f5..542e136a8 100644
--- a/packages/cli/src/integrations/project-integration-writers.test.ts
+++ b/packages/cli/src/integrations/project-integration-writers.test.ts
@@ -168,6 +168,68 @@ describe('projectSkillWriter', () => {
expect(existsSync(outcome.path ?? '')).toBe(true);
});
+ test('does not write the Copilot skill without an OpenKnowledge MCP entry', () => {
+ const outcome = projectSkillWriter.write(EDITOR_TARGETS.copilot, projectDir, {
+ home: tmpRoot,
+ });
+
+ expect(outcome.action).toBe('skipped-prerequisite');
+ expect(outcome.path).toBe(join(projectDir, '.github', 'skills', 'open-knowledge', 'SKILL.md'));
+ expect(existsSync(outcome.path ?? '')).toBe(false);
+ });
+
+ test('writes the Copilot skill when its user-global MCP entry exists', () => {
+ const copilotHome = join(tmpRoot, '.copilot');
+ mkdirSync(copilotHome, { recursive: true });
+ writeFileSync(
+ join(copilotHome, 'mcp-config.json'),
+ JSON.stringify({
+ mcpServers: { 'open-knowledge': { command: 'custom-ok', args: ['mcp'] } },
+ }),
+ );
+
+ const outcome = projectSkillWriter.write(EDITOR_TARGETS.copilot, projectDir, {
+ home: tmpRoot,
+ });
+
+ expect(outcome.action).toBe('written');
+ expect(existsSync(outcome.path ?? '')).toBe(true);
+ });
+
+ test('does not read an oversized Copilot MCP config as a skill prerequisite', () => {
+ const copilotHome = join(tmpRoot, '.copilot');
+ mkdirSync(copilotHome, { recursive: true });
+ writeFileSync(
+ join(copilotHome, 'mcp-config.json'),
+ `${JSON.stringify({
+ mcpServers: { 'open-knowledge': { command: 'custom-ok', args: ['mcp'] } },
+ })}${' '.repeat(10 * 1024 * 1024)}`,
+ );
+
+ const outcome = projectSkillWriter.write(EDITOR_TARGETS.copilot, projectDir, {
+ home: tmpRoot,
+ });
+
+ expect(outcome.action).toBe('skipped-prerequisite');
+ expect(existsSync(outcome.path ?? '')).toBe(false);
+ });
+
+ test('does not write the Copilot skill when only shared project MCP wiring exists', () => {
+ writeFileSync(
+ join(projectDir, '.mcp.json'),
+ JSON.stringify({
+ mcpServers: { 'open-knowledge': { command: 'custom-ok', args: ['mcp'] } },
+ }),
+ );
+
+ const outcome = projectSkillWriter.write(EDITOR_TARGETS.copilot, projectDir, {
+ home: tmpRoot,
+ });
+
+ expect(outcome.action).toBe('skipped-prerequisite');
+ expect(existsSync(outcome.path ?? '')).toBe(false);
+ });
+
test('replaces an existing skill and reports action "overwritten"', () => {
// First write seeds the skill tree.
const first = projectSkillWriter.write(EDITOR_TARGETS.claude, projectDir, {});
diff --git a/packages/cli/src/integrations/project-integration-writers.ts b/packages/cli/src/integrations/project-integration-writers.ts
index 390576de7..f0f1544ef 100644
--- a/packages/cli/src/integrations/project-integration-writers.ts
+++ b/packages/cli/src/integrations/project-integration-writers.ts
@@ -36,6 +36,7 @@ type IntegrationId = 'mcp-config' | 'project-skill';
* - `'overwritten'` — replaced an existing artifact
* - `'skipped-unsupported'` — editor has no surface for this integration
* (e.g. Claude Desktop has no `projectConfigPath` / no `projectSkillPath`)
+ * - `'skipped-prerequisite'` — the editor's required MCP entry is absent
* - `'declined'` — a present config OK can't safely edit was left
* byte-unchanged (guest-ownership); `reason` is the bounded cause. NOT a
* failure — registration was skipped non-destructively.
@@ -48,7 +49,13 @@ type IntegrationId = 'mcp-config' | 'project-skill';
export interface IntegrationWriteOutcome {
readonly integration: IntegrationId;
readonly editorId: EditorId;
- readonly action: 'written' | 'overwritten' | 'skipped-unsupported' | 'declined' | 'failed';
+ readonly action:
+ | 'written'
+ | 'overwritten'
+ | 'skipped-unsupported'
+ | 'skipped-prerequisite'
+ | 'declined'
+ | 'failed';
readonly path?: string;
readonly error?: string;
readonly reason?: McpDeclineReason;
@@ -155,12 +162,9 @@ export const mcpConfigWriter: ProjectIntegrationWriter = {
export const projectSkillWriter: ProjectIntegrationWriter = {
id: 'project-skill',
- // `_options` is intentionally unused — `writeProjectSkill` copies a bundled
- // asset directory; none of the McpInstallOptions fields apply. Accepted so
- // every writer has the same call signature.
- write(target, projectDir, _options) {
+ write(target, projectDir, options) {
try {
- const result = writeProjectSkill(target, projectDir);
+ const result = writeProjectSkill(target, projectDir, { home: options.home });
return {
integration: 'project-skill',
editorId: target.id,
diff --git a/packages/cli/src/integrations/write-project-skill.ts b/packages/cli/src/integrations/write-project-skill.ts
index cc498bfe3..50a251aa9 100644
--- a/packages/cli/src/integrations/write-project-skill.ts
+++ b/packages/cli/src/integrations/write-project-skill.ts
@@ -5,9 +5,19 @@
* (`writeProjectAiIntegrations`) install the project-level runtime skill
* through this one shared implementation.
*/
-import { cpSync, existsSync, lstatSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
+import {
+ cpSync,
+ existsSync,
+ lstatSync,
+ mkdirSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ statSync,
+} from 'node:fs';
import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
import { resolveBundledSkillDir } from '@inkeep/open-knowledge-server';
+import { type ParseError, parse as parseJsonc } from 'jsonc-parser';
import type { EditorId, EditorMcpTarget } from '../commands/editors.ts';
// ---------------------------------------------------------------------------
@@ -104,12 +114,82 @@ function assertProjectAncestorsContained(targetPath: string, cwd: string): void
export interface ProjectSkillResult {
readonly editorId: EditorId;
readonly label: string;
- readonly action: 'written' | 'overwritten' | 'skipped-unsupported' | 'failed';
+ readonly action:
+ | 'written'
+ | 'overwritten'
+ | 'skipped-unsupported'
+ | 'skipped-prerequisite'
+ | 'failed';
readonly path: string;
readonly error?: string;
}
-export function writeProjectSkill(target: EditorMcpTarget, cwd: string): ProjectSkillResult {
+export interface ProjectSkillWriteOptions {
+ readonly home?: string;
+}
+
+const MCP_CONFIG_MAX_BYTES = 10 * 1024 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function configHasOpenKnowledgeEntry(
+ target: EditorMcpTarget,
+ cwd: string,
+ configPath: string,
+): boolean {
+ try {
+ if (statSync(configPath).size > MCP_CONFIG_MAX_BYTES) return false;
+ } catch {
+ return false;
+ }
+
+ let raw: string;
+ try {
+ raw = readFileSync(configPath, 'utf-8');
+ } catch {
+ return false;
+ }
+
+ const errors: ParseError[] = [];
+ const parsed = parseJsonc(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw, errors, {
+ allowTrailingComma: true,
+ disallowComments: false,
+ });
+ if (errors.length > 0 || !isRecord(parsed)) return false;
+
+ const topLevel = parsed[target.topLevelKey];
+ if (!isRecord(topLevel)) return false;
+ const serverMap = target.serverMapSubKey ? topLevel[target.serverMapSubKey] : topLevel;
+ if (!isRecord(serverMap)) return false;
+ return isRecord(serverMap[target.serverName(cwd)]);
+}
+
+/**
+ * Copilot loads OK's runtime skill from the project but its MCP registration
+ * from user-global config. Shared project MCP wiring belongs to other hosts and
+ * cannot satisfy Copilot's prerequisite.
+ */
+function isProjectSkillPrerequisiteMet(
+ target: EditorMcpTarget,
+ cwd: string,
+ options: ProjectSkillWriteOptions = {},
+): boolean {
+ if (target.id !== 'copilot') return true;
+
+ try {
+ return configHasOpenKnowledgeEntry(target, cwd, target.configPath(cwd, options.home));
+ } catch {
+ return false;
+ }
+}
+
+export function writeProjectSkill(
+ target: EditorMcpTarget,
+ cwd: string,
+ options: ProjectSkillWriteOptions = {},
+): ProjectSkillResult {
const skillPath = target.projectSkillPath?.(cwd);
if (!skillPath) {
return {
@@ -119,6 +199,14 @@ export function writeProjectSkill(target: EditorMcpTarget, cwd: string): Project
path: '',
};
}
+ if (!isProjectSkillPrerequisiteMet(target, cwd, options)) {
+ return {
+ editorId: target.id,
+ label: target.label,
+ action: 'skipped-prerequisite',
+ path: skillPath,
+ };
+ }
try {
// The rich `project` bundle — `name: open-knowledge` — installs
diff --git a/packages/cli/src/sharing/git-exclude.test.ts b/packages/cli/src/sharing/git-exclude.test.ts
index 70d12b605..fe7713e7b 100644
--- a/packages/cli/src/sharing/git-exclude.test.ts
+++ b/packages/cli/src/sharing/git-exclude.test.ts
@@ -48,7 +48,7 @@ describe('getOkArtifactPaths', () => {
rmSync(dir, { recursive: true, force: true });
});
- it('returns the canonical thirteen-path artifact set when no config.yml exists', () => {
+ it('returns the canonical fourteen-path artifact set when no config.yml exists', () => {
const paths = getOkArtifactPaths(dir);
expect(paths).toContain(`${OK_DIR}/`);
expect(paths).toContain('.okignore');
@@ -59,6 +59,7 @@ describe('getOkArtifactPaths', () => {
expect(paths).toContain('.claude/skills/open-knowledge/');
expect(paths).toContain('.cursor/skills/open-knowledge/');
expect(paths).toContain('.codex/skills/open-knowledge/');
+ expect(paths).toContain('.github/skills/open-knowledge/');
// OpenCode installs into its own `.opencode/skills/` (its own primary dir,
// not a shared `.agents/skills/` write), so it adds a distinct skill path on
// top of its `opencode.json` config.
@@ -68,7 +69,7 @@ describe('getOkArtifactPaths', () => {
expect(paths).toContain('.pi/extensions/open-knowledge.ts');
expect(paths).toContain('.pi/skills/open-knowledge/');
expect(paths).toContain('.claude/launch.json');
- expect(paths).toHaveLength(13);
+ expect(paths).toHaveLength(14);
});
it('preserves a stable order so `ok config-sharing status` and unit-test snapshots are deterministic', () => {
@@ -91,9 +92,9 @@ describe('getOkArtifactPaths', () => {
expect(paths).not.toContain('docs/.ok/');
expect(paths).not.toContain('docs/.okignore');
expect(paths.some((p) => p.includes('**'))).toBe(false);
- // content.dir must not inflate the set — same thirteen paths as the
+ // content.dir must not inflate the set — same fourteen paths as the
// no-config case, just never `<contentDir>`-prefixed.
- expect(paths).toHaveLength(13);
+ expect(paths).toHaveLength(14);
});
it('excludes each installed skill projection per the OF3 marker (PRD-6934 C9 fix)', () => {
@@ -108,7 +109,7 @@ describe('getOkArtifactPaths', () => {
schema: 1,
skills: {
'trip-log': {
- hosts: ['claude', 'cursor'],
+ hosts: ['claude', 'cursor', 'copilot'],
contentHash: 'abc',
scope: 'project',
scripts: false,
@@ -128,6 +129,7 @@ describe('getOkArtifactPaths', () => {
const paths = getOkArtifactPaths(dir);
expect(paths).toContain('.claude/skills/trip-log/');
expect(paths).toContain('.cursor/skills/trip-log/');
+ expect(paths).toContain('.github/skills/trip-log/');
expect(paths).toContain('.codex/skills/fishing-pack/'); // codex → .codex
// The shipped bundle excludes remain alongside the authored ones.
expect(paths).toContain('.claude/skills/open-knowledge/');
@@ -137,7 +139,7 @@ describe('getOkArtifactPaths', () => {
mkdirSync(join(dir, OK_DIR, 'local'), { recursive: true });
writeFileSync(join(dir, OK_DIR, 'local', 'installed-skills.json'), '{ corrupt', 'utf-8');
const paths = getOkArtifactPaths(dir);
- expect(paths).toHaveLength(13); // corrupt marker → fail-soft, no per-skill paths
+ expect(paths).toHaveLength(14); // corrupt marker → fail-soft, no per-skill paths
});
});
diff --git a/packages/core/src/constants/editors.ts b/packages/core/src/constants/editors.ts
index 71104c0fa..3ac23edfc 100644
--- a/packages/core/src/constants/editors.ts
+++ b/packages/core/src/constants/editors.ts
@@ -11,6 +11,7 @@ export type EditorId =
| 'claude-desktop'
| 'cursor'
| 'codex'
+ | 'copilot'
| 'opencode'
| 'openclaw'
| 'pi'
@@ -23,6 +24,7 @@ export const ALL_EDITOR_IDS = [
'claude-desktop',
'cursor',
'codex',
+ 'copilot',
'opencode',
'openclaw',
'pi',
@@ -42,6 +44,7 @@ export const EDITOR_LABELS = {
'claude-desktop': 'Claude Desktop',
cursor: 'Cursor',
codex: 'Codex',
+ copilot: 'GitHub Copilot',
opencode: 'OpenCode',
openclaw: 'OpenClaw',
pi: 'Pi',
@@ -60,7 +63,7 @@ export const EDITOR_LABELS = {
*
* Each editor installs into its OWN primary skills dir so "install on Codex
* only" is honest. Codex's is `.codex/skills` (alongside its `.codex/config.toml`
- * MCP path).
+ * MCP path); Copilot's is `.github/skills`, its documented project location.
*
* Why per-editor and NOT a shared `.agents/skills` broadcast at project scope:
* `.agents/skills` was Codex's old shared path and conflated Cursor+Codex. At
@@ -91,6 +94,7 @@ export const EDITOR_PROJECT_SKILL_ROOT = {
'claude-desktop': null,
cursor: '.cursor/skills',
codex: '.codex/skills',
+ copilot: '.github/skills',
// OpenCode scans `.opencode/skills` natively (alongside `.agents/skills` and
// `.claude/skills`); OK writes its own primary dir so install-on-OpenCode is
// honest and never shares Codex's write.
@@ -133,21 +137,22 @@ export const PROJECT_SKILL_EDITOR_IDS = ALL_EDITOR_IDS.filter(
* canonical editor constants. Adding a project-skill editor to
* `EDITOR_PROJECT_SKILL_ROOT` flows here automatically.
*
- * Pi is the one carve-out: its user-global skills dir is `~/.pi/agent/skills`
- * (the agent home is nested one level below the `.pi` dotdir), NOT the
- * `~/<hostDir>/skills` layout this derivation assumes — and Pi natively reads
- * the central `~/.agents/skills` hub, which the user-bundle installer already
- * writes. Including it here would create a dead `~/.pi/skills/` dir nothing
- * reads.
+ * Pi and Copilot are carve-outs: Pi's user-global skills dir is
+ * `~/.pi/agent/skills` (the agent home is nested one level below the `.pi`
+ * dotdir), while Copilot's is `~/.copilot/skills`, not `~/.github/skills`.
+ * Both natively read the central `~/.agents/skills` hub that the user-bundle
+ * installer already writes, so including either here would create a dead path.
*/
export const HOSTS_WITH_USER_SKILL_DIR: ReadonlyArray<{
readonly hostDir: string;
readonly editorId: EditorId;
-}> = PROJECT_SKILL_EDITOR_IDS.filter((editorId) => editorId !== 'pi').map((editorId) => ({
- // `editorId` came from the non-null filter, so the root is a string.
- hostDir: (EDITOR_PROJECT_SKILL_ROOT[editorId] ?? '').split('/')[0],
- editorId,
-}));
+}> = PROJECT_SKILL_EDITOR_IDS.filter((editorId) => editorId !== 'pi' && editorId !== 'copilot').map(
+ (editorId) => ({
+ // `editorId` came from the non-null filter, so the root is a string.
+ hostDir: (EDITOR_PROJECT_SKILL_ROOT[editorId] ?? '').split('/')[0],
+ editorId,
+ }),
+);
/**
* OpenKnowledge integration-doc slug per editor — the setup guide at
@@ -160,6 +165,7 @@ export const EDITOR_SETUP_DOC_SLUG = {
'claude-desktop': 'claude-code',
cursor: 'cursor',
codex: 'codex',
+ copilot: 'github-copilot-cli',
opencode: 'opencode',
openclaw: 'openclaw',
pi: 'pi',
@@ -181,6 +187,12 @@ export const EDITOR_PROJECT_CONFIG_PATH = {
'claude-desktop': null,
cursor: '.cursor/mcp.json',
codex: '.codex/config.toml',
+ // Copilot's `~/.copilot/mcp-config.json` is user-global. It can also read
+ // standard workspace `.mcp.json` files, but OK does not duplicate its own
+ // server into the shared Claude workspace config: one user-global entry
+ // avoids same-named-source precedence ambiguity while project skills still
+ // install to `.github/skills`.
+ copilot: null,
opencode: 'opencode.json',
// OpenClaw's MCP config is user-global (`~/.openclaw/openclaw.json`); no
// project-local variant, so it is never detected as "project-configured".
diff --git a/packages/core/src/handoff/terminal-launch.test.ts b/packages/core/src/handoff/terminal-launch.test.ts
index 5286ab02a..84e7ae295 100644
--- a/packages/core/src/handoff/terminal-launch.test.ts
+++ b/packages/core/src/handoff/terminal-launch.test.ts
@@ -18,7 +18,7 @@ const OK_ALLOW = `["mcp__${MCP_SERVER_NAME}","Bash(ok open:*)"]`;
const OK_DENY = `["mcp__${MCP_SERVER_NAME}__delete","mcp__${MCP_SERVER_NAME}__move","mcp__${MCP_SERVER_NAME}__share_link","mcp__${MCP_SERVER_NAME}__install"]`;
describe('TERMINAL_CLI_IDS', () => {
- it('lists the CLIs in auto-pick priority order (claude > codex > opencode > cursor > pi > antigravity)', () => {
+ it('lists the CLIs in auto-pick priority order (claude > codex > opencode > cursor > copilot > pi > antigravity)', () => {
// The single constant drives both the visible launch-row order and the
// default-CLI auto-pick, so display and defaulting can never disagree.
expect([...TERMINAL_CLI_IDS]).toEqual([
@@ -26,6 +26,7 @@ describe('TERMINAL_CLI_IDS', () => {
'codex',
'opencode',
'cursor',
+ 'copilot',
'pi',
'antigravity',
]);
@@ -121,6 +122,7 @@ describe('buildCliLaunchCommand', () => {
// which opens the GUI editor). Without opting in, even claude is bare.
expect(buildCliLaunchCommand('claude', 'hi')).toBe("claude 'hi'\r");
expect(buildCliLaunchCommand('codex', 'hi')).toBe("codex 'hi'\r");
+ expect(buildCliLaunchCommand('copilot', 'hi')).toBe("copilot --interactive 'hi'\r");
expect(buildCliLaunchCommand('cursor', 'hi')).toBe("cursor-agent 'hi'\r");
// OpenCode's positional is the project dir, so the prompt rides on --prompt.
expect(buildCliLaunchCommand('opencode', 'hi')).toBe("opencode --prompt 'hi'\r");
@@ -162,6 +164,7 @@ describe('buildCliLaunchArgString', () => {
it('keeps the fixed per-CLI shape (registry bin + single-quoted prompt)', () => {
expect(buildCliLaunchArgString('claude', 'hi')).toBe("claude 'hi'");
expect(buildCliLaunchArgString('codex', 'hi')).toBe("codex 'hi'");
+ expect(buildCliLaunchArgString('copilot', 'hi')).toBe("copilot --interactive 'hi'");
expect(buildCliLaunchArgString('cursor', 'hi')).toBe("cursor-agent 'hi'");
expect(buildCliLaunchArgString('opencode', 'hi')).toBe("opencode --prompt 'hi'");
expect(buildCliLaunchArgString('pi', 'hi')).toBe("pi 'hi'");
@@ -180,6 +183,7 @@ describe('buildCliLaunchArgString promptless (New chat)', () => {
for (const emptyPrompt of [null, undefined, ''] as const) {
expect(buildCliLaunchArgString('claude', emptyPrompt)).toBe('claude');
expect(buildCliLaunchArgString('codex', emptyPrompt)).toBe('codex');
+ expect(buildCliLaunchArgString('copilot', emptyPrompt)).toBe('copilot');
expect(buildCliLaunchArgString('cursor', emptyPrompt)).toBe('cursor-agent');
// OpenCode carries a prompt on `--prompt`; with no prompt the flag is
// dropped entirely so the bare TUI opens (positional stays the cwd).
@@ -235,8 +239,11 @@ describe('claude MCP pre-approval', () => {
);
});
- it('never added for codex/cursor/opencode, even when opted in (claude-only flag)', () => {
+ it('never added for codex/copilot/cursor/opencode, even when opted in (claude-only flag)', () => {
expect(buildCliLaunchCommand('codex', 'hi', { mcpPreApprove: true })).toBe("codex 'hi'\r");
+ expect(buildCliLaunchCommand('copilot', 'hi', { mcpPreApprove: true })).toBe(
+ "copilot --interactive 'hi'\r",
+ );
expect(buildCliLaunchCommand('cursor', 'hi', { mcpPreApprove: true })).toBe(
"cursor-agent 'hi'\r",
);
@@ -284,7 +291,10 @@ describe('OK auto-approve (autoApproveOkTools)', () => {
expect(buildCliLaunchArgString('codex', 'hi')).toBe("codex 'hi'");
});
- it('is claude/codex only — cursor/opencode/pi never get an auto-approve arg', () => {
+ it('is claude/codex only — copilot/cursor/opencode/pi never get an auto-approve arg', () => {
+ expect(buildCliLaunchArgString('copilot', 'hi', { autoApproveOkTools: true })).toBe(
+ "copilot --interactive 'hi'",
+ );
expect(buildCliLaunchArgString('cursor', 'hi', { autoApproveOkTools: true })).toBe(
"cursor-agent 'hi'",
);
diff --git a/packages/core/src/handoff/terminal-launch.ts b/packages/core/src/handoff/terminal-launch.ts
index 133c3b634..aebcbdfd6 100644
--- a/packages/core/src/handoff/terminal-launch.ts
+++ b/packages/core/src/handoff/terminal-launch.ts
@@ -44,7 +44,14 @@ export function shellSingleQuote(s: string): string {
* one-shot variants: `codex exec` and `cursor-agent -p` both run-and-exit, so
* the session wouldn't stay open for the user to continue in).
*/
-export type TerminalCli = 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'antigravity';
+export type TerminalCli =
+ | 'claude'
+ | 'codex'
+ | 'copilot'
+ | 'cursor'
+ | 'opencode'
+ | 'pi'
+ | 'antigravity';
export interface TerminalCliInfo {
/** PATH binary launched in the PTY. Interpolated (alongside any opted-in
@@ -168,6 +175,15 @@ export const TERMINAL_CLIS = {
handoffTarget: 'codex',
autoApproveArg: CODEX_OK_AUTO_APPROVE_ARG,
},
+ copilot: {
+ // Copilot's `--prompt` mode exits after one response. `--interactive`
+ // executes the starting prompt but keeps the session open for follow-up.
+ bin: 'copilot',
+ displayName: 'GitHub Copilot',
+ docsUrl: 'https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-getting-started',
+ handoffTarget: 'copilot',
+ promptFlag: '--interactive',
+ },
cursor: {
bin: 'cursor-agent',
displayName: 'Cursor',
@@ -214,13 +230,16 @@ export const TERMINAL_CLIS = {
/**
* Stable launch order — drives the menu rows and any iteration over CLIs. Order
* is also the default-CLI auto-pick priority (first installed wins), so the
- * visible row order and the resolved default can never disagree.
+ * visible row order and the resolved default can never disagree. Copilot is
+ * placed after the established primary CLI defaults to avoid changing an
+ * existing multi-CLI user's first-run selection.
*/
export const TERMINAL_CLI_IDS = [
'claude',
'codex',
'opencode',
'cursor',
+ 'copilot',
'pi',
'antigravity',
] as const satisfies readonly TerminalCli[];
diff --git a/packages/core/src/handoff/types.ts b/packages/core/src/handoff/types.ts
index 9403ee41f..42f027c36 100644
--- a/packages/core/src/handoff/types.ts
+++ b/packages/core/src/handoff/types.ts
@@ -3,8 +3,8 @@
* pure type surface consumable from Electron main, renderer, and server.
*/
-// `opencode`, `pi`, and `antigravity` are TERMINAL-ONLY targets: OK reaches
-// them via the `agy`/`opencode`/`pi` CLI, not a URL scheme / GUI app, so they
+// `copilot`, `opencode`, `pi`, and `antigravity` are TERMINAL-ONLY targets: OK
+// reaches them via their CLIs, not a URL scheme / GUI app, so they
// are carved out of the deep-link dispatch path (no `RECIPES` recipe, no
// `dispatch.ts` URL case, excluded from `VISIBLE_TARGETS`). They are members of
// the union only so they can reuse the shared brand-icon + display-name
@@ -14,6 +14,7 @@ export type HandoffTarget =
| 'claude-cowork'
| 'claude-code'
| 'codex'
+ | 'copilot'
| 'cursor'
| 'opencode'
| 'pi'
diff --git a/packages/core/src/skill-targets/editor-single-source.test.ts b/packages/core/src/skill-targets/editor-single-source.test.ts
index 66f6e4147..32d60fe08 100644
--- a/packages/core/src/skill-targets/editor-single-source.test.ts
+++ b/packages/core/src/skill-targets/editor-single-source.test.ts
@@ -40,12 +40,12 @@ describe('project-skill editor-id single source', () => {
test('HOSTS_WITH_USER_SKILL_DIR derives from the same editors (CLI repair-skills ↔ desktop skill-reclaim share it)', () => {
// Single source for the host-dir sweep both the CLI and desktop run.
- // editorId set === PROJECT_SKILL_EDITOR_IDS minus the documented Pi
- // carve-out (Pi's user-global skills dir is `~/.pi/agent/skills`, not the
- // `~/<hostDir>/skills` layout this sweep assumes, and Pi reads the central
- // `~/.agents/skills` hub natively); hostDir === the root's top-level dotdir.
+ // editorId set === PROJECT_SKILL_EDITOR_IDS minus the documented Pi and
+ // Copilot carve-outs. Their user-global skills dirs do not follow the
+ // `~/<hostDir>/skills` layout this sweep assumes; both read the central
+ // `~/.agents/skills` hub natively. hostDir === the root's top-level dotdir.
expect(asStrings(HOSTS_WITH_USER_SKILL_DIR.map((h) => h.editorId))).toEqual(
- asStrings(PROJECT_SKILL_EDITOR_IDS.filter((id) => id !== 'pi')),
+ asStrings(PROJECT_SKILL_EDITOR_IDS.filter((id) => id !== 'pi' && id !== 'copilot')),
);
for (const { hostDir, editorId } of HOSTS_WITH_USER_SKILL_DIR) {
expect(hostDir).toBe((EDITOR_PROJECT_SKILL_ROOT[editorId] ?? '').split('/')[0]);
@@ -63,6 +63,14 @@ describe('project-skill editor-id single source', () => {
expect(HOSTS_WITH_USER_SKILL_DIR.map((h) => h.hostDir)).not.toContain('.pi');
});
+ test('Copilot IS a project-skill install target but NOT a user-global host-dir sweep member', () => {
+ // Copilot scans `.github/skills` per project, but keeps global skills at
+ // `~/.copilot/skills`; it also reads the central `~/.agents/skills` hub.
+ expect(SkillTargetEditorSchema.options).toContain('copilot');
+ expect(HOSTS_WITH_USER_SKILL_DIR.map((h) => h.editorId)).not.toContain('copilot');
+ expect(HOSTS_WITH_USER_SKILL_DIR.map((h) => h.hostDir)).not.toContain('.github');
+ });
+
test('Claude Desktop is NOT a project-skill install target (user-global only, null root)', () => {
// Regression: the install menu / picker must not offer claude-desktop —
// it has no project skill surface (reads user-global skills only).
diff --git a/packages/core/src/skill-targets/schema.ts b/packages/core/src/skill-targets/schema.ts
index 23ccc467c..4886a8064 100644
--- a/packages/core/src/skill-targets/schema.ts
+++ b/packages/core/src/skill-targets/schema.ts
@@ -14,7 +14,7 @@
* absent, OK falls back to the editors the project is already configured for.
*
* Only editors with a project skill surface are valid targets
- * (`claude` / `cursor` / `codex` / `opencode` / `pi`; Claude Desktop, OpenClaw,
+ * (`claude` / `cursor` / `codex` / `copilot` / `opencode` / `pi`; Claude Desktop, OpenClaw,
* and Antigravity read user-global skills only).
*/
@@ -38,7 +38,7 @@ export const SKILL_TARGETS_SCHEMA_VERSION = 1;
* `.filter` widens to `EditorId`, so the cast restates the narrow literal shape:
* `Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'antigravity' | 'hermes'>`
* is exactly the set of editors WITH a project skill surface (`claude` /
- * `cursor` / `codex` / `opencode` / `pi`). claude-desktop, openclaw,
+ * `cursor` / `codex` / `copilot` / `opencode` / `pi`). claude-desktop, openclaw,
* antigravity, and hermes have a null project skill root (user-global skills
* only), so they are excluded. schema.test.ts asserts the cast stays
* value-equal to the derived list as a backstop.
diff --git a/packages/desktop/src/main/create-new-project.test.ts b/packages/desktop/src/main/create-new-project.test.ts
index 128ff05b8..20aa5b86a 100644
--- a/packages/desktop/src/main/create-new-project.test.ts
+++ b/packages/desktop/src/main/create-new-project.test.ts
@@ -551,12 +551,28 @@ describe('runCreateNew — installs the project-local skill (PRD-6733)', () => {
// `writeProjectAiIntegrations` now routes through `applyProjectIntegrations`
// (the same orchestrator the onboarding-consent path uses), so both desktop
// project-setup entry points install the skill.
- test('installs the open-knowledge project skill for claude, cursor, and codex', async () => {
- const result = await runCreateNew({
- parent: tmpRoot,
- name: 'Skill Install',
- editors: [...ALL_EDITOR_IDS],
- });
+ test('installs project skills when the selected editors provide MCP wiring', async () => {
+ const originalCopilotHome = process.env.COPILOT_HOME;
+ const copilotHome = join(tmpRoot, 'copilot-with-mcp');
+ process.env.COPILOT_HOME = copilotHome;
+ mkdirSync(copilotHome, { recursive: true });
+ writeFileSync(
+ join(copilotHome, 'mcp-config.json'),
+ JSON.stringify({
+ mcpServers: { 'open-knowledge': { command: 'custom-ok', args: ['mcp'] } },
+ }),
+ );
+ let result: Awaited<ReturnType<typeof runCreateNew>>;
+ try {
+ result = await runCreateNew({
+ parent: tmpRoot,
+ name: 'Skill Install',
+ editors: [...ALL_EDITOR_IDS],
+ });
+ } finally {
+ if (originalCopilotHome === undefined) delete process.env.COPILOT_HOME;
+ else process.env.COPILOT_HOME = originalCopilotHome;
+ }
expect(
existsSync(join(result.projectDir, '.claude', 'skills', 'open-knowledge', 'SKILL.md')),
@@ -567,13 +583,15 @@ describe('runCreateNew — installs the project-local skill (PRD-6733)', () => {
expect(
existsSync(join(result.projectDir, '.codex', 'skills', 'open-knowledge', 'SKILL.md')),
).toBe(true);
+ expect(
+ existsSync(join(result.projectDir, '.github', 'skills', 'open-knowledge', 'SKILL.md')),
+ ).toBe(true);
expect(
existsSync(join(result.projectDir, '.opencode', 'skills', 'open-knowledge', 'SKILL.md')),
).toBe(true);
expect(existsSync(join(result.projectDir, '.pi', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(
true,
);
-
// The result's `aiIntegrations` carries the per-(editor × integration)
// outcomes — the project-skill writer ran and reported success for every
// editor that has a project skill surface.
@@ -583,11 +601,39 @@ describe('runCreateNew — installs the project-local skill (PRD-6733)', () => {
expect(skillWrites.map((o) => o.editorId).sort()).toEqual([
'claude',
'codex',
+ 'copilot',
'cursor',
'opencode',
'pi',
]);
});
+
+ test('skips the Copilot project skill when Copilot is selected without MCP wiring', async () => {
+ const originalCopilotHome = process.env.COPILOT_HOME;
+ process.env.COPILOT_HOME = join(tmpRoot, 'copilot-without-mcp');
+ let result: Awaited<ReturnType<typeof runCreateNew>>;
+ try {
+ result = await runCreateNew({
+ parent: tmpRoot,
+ name: 'Copilot Without MCP',
+ editors: ['copilot'],
+ });
+ } finally {
+ if (originalCopilotHome === undefined) delete process.env.COPILOT_HOME;
+ else process.env.COPILOT_HOME = originalCopilotHome;
+ }
+
+ expect(
+ existsSync(join(result.projectDir, '.github', 'skills', 'open-knowledge', 'SKILL.md')),
+ ).toBe(false);
+ expect(result.aiIntegrations.integrations).toContainEqual(
+ expect.objectContaining({
+ editorId: 'copilot',
+ integration: 'project-skill',
+ action: 'skipped-prerequisite',
+ }),
+ );
+ });
});
describe('runCreateNew — starter-pack seeding', () => {
diff --git a/packages/desktop/src/main/project-integrations-settings.ts b/packages/desktop/src/main/project-integrations-settings.ts
index 7bde3f0d9..34ed73cb4 100644
--- a/packages/desktop/src/main/project-integrations-settings.ts
+++ b/packages/desktop/src/main/project-integrations-settings.ts
@@ -102,7 +102,10 @@ export interface ProjectIntegrationsCliSurface {
writeProjectSkill(
id: McpWiringEditorId,
projectDir: string,
- ): { action: 'written' | 'overwritten' | 'skipped-unsupported' | 'failed'; error?: string };
+ ): {
+ action: 'written' | 'overwritten' | 'skipped-unsupported' | 'skipped-prerequisite' | 'failed';
+ error?: string;
+ };
removeProjectSkill(
id: McpWiringEditorId,
projectDir: string,
diff --git a/packages/desktop/tests/integration/m1-smoke.test.ts b/packages/desktop/tests/integration/m1-smoke.test.ts
index 2b69baf28..9b80c496e 100644
--- a/packages/desktop/tests/integration/m1-smoke.test.ts
+++ b/packages/desktop/tests/integration/m1-smoke.test.ts
@@ -401,9 +401,9 @@ describe('M1 smoke', () => {
typeName: 'EditorId',
canonicalPath: editorsConstantPath,
canonicalRe: /type\s+EditorId\s*=([^;]+);/,
- expectedLiteralCount: 10,
+ expectedLiteralCount: 11,
inlineRe:
- /'claude'\s*\|\s*'claude-desktop'\s*\|\s*'cursor'\s*\|\s*'codex'\s*\|\s*'opencode'\s*\|\s*'openclaw'/,
+ /'claude'\s*\|\s*'claude-desktop'\s*\|\s*'cursor'\s*\|\s*'codex'\s*\|\s*'copilot'\s*\|\s*'opencode'\s*\|\s*'openclaw'/,
mirrors: [
['cli/commands/editors.ts', cliEditorsPath],
['desktop/shared/ipc-channels.ts', ipcChannelsPath],
diff --git a/packages/desktop/tests/main/claude-readiness.test.ts b/packages/desktop/tests/main/claude-readiness.test.ts
index d91429550..24d8cd979 100644
--- a/packages/desktop/tests/main/claude-readiness.test.ts
+++ b/packages/desktop/tests/main/claude-readiness.test.ts
@@ -307,6 +307,7 @@ describe('resolveCliInstalledMap', () => {
const codes: Record<TerminalCli, number | null> = {
claude: 0,
codex: 127,
+ copilot: 0,
opencode: null,
cursor: 0,
pi: 127,
@@ -315,6 +316,7 @@ describe('resolveCliInstalledMap', () => {
expect(await resolveCliInstalledMap({ probe: (cli) => Promise.resolve(codes[cli]) })).toEqual({
claude: true,
codex: false,
+ copilot: true,
opencode: false,
cursor: true,
pi: false,
@@ -329,6 +331,7 @@ describe('resolveCliInstalledMap', () => {
expect(map).toEqual({
claude: true,
codex: false,
+ copilot: true,
opencode: true,
cursor: true,
pi: true,
diff --git a/packages/server/src/handoff-dispatch-api.ts b/packages/server/src/handoff-dispatch-api.ts
index 9c7c59e1b..93525f13a 100644
--- a/packages/server/src/handoff-dispatch-api.ts
+++ b/packages/server/src/handoff-dispatch-api.ts
@@ -140,20 +140,21 @@ const RECIPES = {
binaryName: 'cursor',
urlScheme: 'cursor:',
},
- // `opencode`, `pi`, and `antigravity` are intentionally absent: they are
+ // `copilot`, `opencode`, `pi`, and `antigravity` are intentionally absent:
// terminal-only targets with no URL scheme, dispatched via the terminal-CLI
- // path (`requestTerminalLaunch`), never this deep-link endpoint. They are
- // excluded from the exhaustiveness gate via `Exclude<…>` so the build does
- // not demand (nonexistent) URL recipes for them.
-} as const satisfies Record<Exclude<HandoffTarget, 'opencode' | 'pi' | 'antigravity'>, Recipe>;
+ // path (`requestTerminalLaunch`), never this deep-link endpoint.
+} as const satisfies Record<
+ Exclude<HandoffTarget, 'copilot' | 'opencode' | 'pi' | 'antigravity'>,
+ Recipe
+>;
// Narrowed to the URL-dispatchable subset: `RECIPES` omits the terminal-only
-// `opencode` / `pi` / `antigravity` targets, so its keys (and the parsed
-// `target`) exclude them, keeping the `RECIPES[target]` lookup below exhaustive
-// at the type level.
+// `copilot` / `opencode` / `pi` / `antigravity` targets, so its keys (and the
+// parsed `target`) exclude them, keeping the `RECIPES[target]` lookup below
+// exhaustive at the type level.
const TARGET_VALUES = Object.keys(RECIPES) as [
- Exclude<HandoffTarget, 'opencode' | 'pi' | 'antigravity'>,
- ...Exclude<HandoffTarget, 'opencode' | 'pi' | 'antigravity'>[],
+ Exclude<HandoffTarget, 'copilot' | 'opencode' | 'pi' | 'antigravity'>,
+ ...Exclude<HandoffTarget, 'copilot' | 'opencode' | 'pi' | 'antigravity'>[],
];
const HandoffRequestSchema = z.object({
target: z.enum(TARGET_VALUES),