AI harness engineering compatibility matrix
Compare which harness config files each AI coding tool reads, what they control, and how support changes across surfaces.
Scroll horizontally to compare products and surfaces. The config column stays pinned.
| Config file | GitHub CopilotVS Code | GitHub Copilot appDesktop | GitHub Copilot CLITerminal | GitHub CopilotCloud agent | Claude CodeDesktop + CLI + IDE | OpenAI CodexChatGPT app + CLI + IDE | CursorEditor + CLI |
|---|---|---|---|---|---|---|---|
AGENTS.mdroot of repo |
Yes | Yes | Yes | Yes | — | Yes | Yes |
The broadest shared instruction file in this matrix. Put durable repo guidance here: stack, architecture, naming rules, forbidden patterns, and team conventions. GitHub Copilot, OpenAI Codex, and Cursor read it natively. Claude Code uses CLAUDE.md natively and can import a shared AGENTS.md base from there. VS Code reads root-level AGENTS.md by default; nested files remain experimental and off by default. | |||||||
CLAUDE.mdroot + subdirectories |
Yes | Fallback | Fallback | Yes | Yes | — | — |
Claude Code's native repo instruction file. Desktop and CLI share the same hierarchical loading from root and subdirectories. Claude Code reads CLAUDE.md, not AGENTS.md, so import the shared base with @AGENTS.md and keep Claude-specific additions here. GitHub Copilot reads CLAUDE.md as a cross-tool compatibility instruction file — treated as a peer of AGENTS.md rather than a lower-priority fallback. VS Code also searches .claude/CLAUDE.md, ~/.claude/CLAUDE.md, and CLAUDE.local.md. One exception: Copilot code review reads AGENTS.md only. | |||||||
GEMINI.mdroot of repo |
— | — | Fallback | Fallback | — | — | — |
Gemini's instruction file, read by Copilot as a third compatibility format. GitHub's custom-instruction support matrix now lists GEMINI.md alongside AGENTS.md and CLAUDE.md for Copilot CLI and the cloud agent. Copilot code review does not read it. Included here because it shows Copilot converging on "read whatever instruction file the repo already has" rather than requiring its own. | |||||||
copilot-instructions.md.github/ |
Yes | Yes | Yes | Yes | — | — | — |
Copilot's original repo-wide instruction file. It lives at .github/copilot-instructions.md and loads into Copilot requests. Use AGENTS.md for shared rules and this file for Copilot-only additions. Copilot CLI can generate one with /init; VS Code can create one from the Agent Customizations editor. | |||||||
github-app.yml.github/ (app project config) |
— | Yes | — | — | — | — | — |
The GitHub Copilot app's project configuration. .github/github-app.yml stores trusted app-specific instructions, setup/run/archive scripts, server detection, browser behavior, and automation settings. The legacy filename .github/copilot-desktop.yml remains a compatibility alias. | |||||||
*.instructions.md.github/instructions/ (glob scoped) |
Yes | Yes | Yes | Yes | — | — | — |
Copilot path-scoped instructions. Each file uses applyTo frontmatter, such as "**/*.tsx", so rules apply only to matching files. Use these for framework, language, or directory-specific conventions. Claude Code's equivalent is .claude/rules/*.md with paths. | |||||||
.claude/rules/*.mdscoped via paths property |
Fallback | — | — | — | Yes | — | — |
Claude Code's scoped instruction files. They use a paths array instead of Copilot's applyTo. If paths is omitted, the rule defaults to all files. GitHub Copilot in VS Code reads this folder as a Claude-format compatibility location. | |||||||
.cursor/rules/*.mdc.cursor/rules/ (frontmatter scoped) |
— | — | — | — | — | — | Yes |
Cursor's native scoped rules. MDC files in .cursor/rules/ support four activation modes: always-on, glob match, “Apply Intelligently” model selection, and manual @rule-name. When alwaysApply: true, Cursor ignores globs and description. | |||||||
AGENT-NAME.md.github/agents/ |
Yeshard | Yeshard | Yeshard | Yeshard | — | — | — |
Specialized Copilot personas selected by name. Each file defines a role, tool access, model choice, and behavioral boundary, with optional mcp-servers frontmatter. Invoke by choosing the agent from the dropdown in your IDE, on GitHub, or in Copilot CLI — or type /agent in the Copilot app. Repository agents live in .github/agents/; organization and enterprise agents live at /agents/AGENT-NAME.md in a .github or .github-private repository. | |||||||
.claude/agents/*.mdClaude subagents |
Fallback | — | — | — | Yeshard | — | Fallback |
Claude Code's subagent system. These agents run with isolated context and explicit tools across the desktop app, CLI, and editor integrations. Frontmatter covers tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, and isolation: worktree. Built-ins include Explore for read-only research and Plan for planning without file edits. Both GitHub Copilot in VS Code and Cursor read Claude-format agent files as a compatibility location. | |||||||
.codex/agents/*.tomlproject-scoped custom agents |
— | — | — | — | — | Yeshard | Fallback |
OpenAI Codex custom agents. Standalone TOML files in .codex/agents/ or ~/.codex/agents/ define name, description, and developer_instructions, plus optional model, reasoning effort, sandboxing, skills, and MCP servers. Built-ins are default, worker, and explorer. Cursor reads the .codex/agents/ directory as a compatibility location, though it expects Markdown rather than TOML. Codex's own docs note the format "may evolve as authoring and sharing mature," so treat it as less settled than the Markdown agent formats. | |||||||
.cursor/agents/*.mdCursor subagents |
— | — | — | — | — | — | Yeshard |
Cursor's subagent format. Markdown files with YAML frontmatter: name, description, model (defaults to inherit), readonly, and is_background. Project agents live in .cursor/agents/ and user agents in ~/.cursor/agents/; Cursor also reads .claude/agents/ and .codex/agents/ for compatibility, with .cursor/ winning name conflicts and project beating user scope. Built-ins are Explore, Bash, and Browser. Separately, Cursor's Custom Modes are not a config file — any skill can be pinned as a mode with Option/Alt+Enter, styled by optional icon and color frontmatter. | |||||||
.github/skills/*/SKILL.mdCopilot native path |
Yes | Yes | Yes | Yes | — | — | — |
One of Copilot's three first-class skill paths. A skill is a folder with SKILL.md plus optional scripts, templates, and assets. Copilot loads metadata first and the full body only when needed. .claude/skills/ and .agents/skills/ are equally first-class in Copilot. | |||||||
.claude/skills/*/SKILL.mdClaude Code native path |
Yes | Yes | Yes | Yes | Yes | — | Fallback |
Claude Code's native skill path. Claude supports auto-invocation, explicit /skill-name invocation, forked subagent execution, and chaining up to six skills in one command across its local clients. GitHub Copilot reads this as a first-class project skill path, while Cursor supports it as a compatibility location. | |||||||
.agents/skills/*/SKILL.mdcross-agent standard path |
Yes | Yes | Yes | Yes | — | Yes | Yes |
The broadest shared skill path among these products. GitHub Copilot, OpenAI Codex, and Cursor read .agents/skills/ natively. VS Code can add more locations through chat.agentSkillsLocations. The path follows the open Agent Skills specification. | |||||||
.cursor/skills/*/SKILL.mdCursor native path |
— | — | — | — | — | — | Yes |
Cursor's native skill path. Skills live at .cursor/skills/<name>/SKILL.md, or globally at ~/.cursor/skills/, with name and description frontmatter. Cursor loads metadata until invocation and reads .agents/skills/ natively. A skill can also be pinned as a Custom Mode. | |||||||
*.prompt.md.github/prompts/ |
Yes | — | — | — | — | — | — |
Lightweight reusable prompt templates for Copilot IDEs. Invoke with /prompt-name in chat. Prompt files run only in the VS Code extension host; Copilot CLI, the Copilot app, and cloud agents run on Agent Host and do not load them. Convert reusable Agent Host prompts to skills. | |||||||
.claude/commands/*.mdClaude custom commands |
— | — | — | — | Yes | — | — |
Claude Code's legacy slash-command path. Custom commands have merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Existing command files still work, but skills are canonical for new workflows and add supporting files, invocation controls, and auto-invocation. | |||||||
.github/hooks/*.jsonany .json filename |
opt-in | Yes | Yes | Yes | — | — | — |
GitHub Copilot lifecycle hooks. Any .json file in .github/hooks/ is read — the filename is free-form. Events are sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, agentStop, subagentStop, and errorOccurred; preToolUse can approve or deny a tool call. Handlers can be shell commands or HTTP endpoints. Hooks are GA in the Copilot app, CLI, and cloud agent. VS Code support remains in Preview, can read Claude-format .claude/settings.json hooks, and supports chat.hookFilesLocations. | |||||||
.claude/settings.jsonhooks key |
opt-in | — | — | — | Yes | — | — |
Claude Code's hook system — the broadest event surface here, at roughly 28 documented events. Handlers can run shell commands, HTTP endpoints, MCP tools, prompts, or agents. Events cover setup, sessions, prompt submission and expansion, tool use and batches, permission requests and denials, subagents and tasks, compaction, worktrees, config and instruction loading, file and directory changes, MCP elicitation, notifications, display, and stop/failure. The prompt and agent handler types make this the clearest example of an inferential sensor — a model, not a script, deciding whether the agent went wrong. GitHub Copilot in VS Code can read Claude-format hooks in Preview. | |||||||
.codex/hooks.json bothrepo or ~/.codex/ |
— | — | — | — | — | Yesdefault-on | — |
OpenAI Codex lifecycle hooks. Local Codex clients load hooks from active configuration layers. Hooks are enabled by default and can be disabled with [features] hooks = false; codex_hooks is a deprecated alias. Events include sessions, subagents, prompts, tool use, permissions, compaction, and stopping. All matching hooks from active trusted layers run. | |||||||
.cursor/hooks.json bothproject or ~/.cursor/ |
— | — | — | — | — | — | Yes |
Cursor's hook system. Project hooks live at .cursor/hooks.json; user hooks live at ~/.cursor/hooks.json. Command hooks receive JSON on stdin and cover tool use, shell execution, edits, prompts, compaction, sessions, workspace open, agent response/thought, stop, and subagent start/stop events. beforeSubmitPrompt is unavailable on cloud agents. | |||||||
.vscode/mcp.jsonVS Code workspace |
Yes | — | — | — | — | — | — |
Copilot's MCP config for VS Code. Defines workspace servers over stdio or HTTP with environment variables, authentication, and sandboxing. It is committable for team sharing. MCP can also be configured in workspace or user settings, installed from the gallery, or added through devcontainer.json. | |||||||
.mcp.jsonrepo root |
— | Yes | Yes | — | Yes | — | — |
A shared project MCP path for GitHub Copilot and Claude Code. Copilot CLI walks from the working directory to the repository root for .mcp.json; those repository servers are also available in the Copilot app. Claude Code reads a root-level file across its local clients. Both require repository trust before starting committed servers. | |||||||
.github/mcp.jsonshared Copilot repository config |
— | Yes | Yes | Yes | — | — | — |
GitHub Copilot's committed repository MCP path. The app automatically exposes repository and CLI servers, Copilot CLI reads this file after folder trust, and the cloud agent uses it for repository-scoped servers. Use .vscode/mcp.json instead for the VS Code extension host. | |||||||
.codex/config.tomlrepo root (mcp_servers) |
— | — | — | — | — | Yes | — |
OpenAI Codex's project-scoped MCP config. MCP servers are defined under [mcp_servers.<name>] tables in TOML. The ChatGPT desktop app, CLI, and IDE extension share the local configuration layers; user-level config lives at ~/.codex/config.toml. | |||||||
.cursor/mcp.json.cursor/ (project + global) |
— | — | — | — | — | — | Yes |
Cursor's MCP config. Project-scoped at .cursor/mcp.json, user-scoped at ~/.cursor/mcp.json, with team-distributed MCP now available for organizations. Supports stdio, SSE, and streamable HTTP transports. | |||||||
permission rules (allow / deny / ask)file path or UI |
Yessettings.json | Yesapp settings | Yes~/.copilot/ | UI onlyrepo settings | YesUI + settings | YesUI + config | Yes.cursor/cli.json |
How each surface gates calls before execution. GitHub Copilot, Claude Code, OpenAI Codex, and Cursor can match tools, commands, paths, domains, or MCP calls with allow, deny, and ask-style decisions. Claude Code's desktop selector and Codex's local-client permission control layer over their shared settings files. The Copilot cloud agent has no interactive approval because humans review the resulting pull request. | |||||||
OS-level sandboxfilesystem + network isolation |
— | opt-inMXC preview | opt-inMXC preview | YesActions VM | YesSeatbelt / Bubblewrap | Yesplatform native | YesSeatbelt / Landlock / WSL2 |
OS-level isolation goes beyond permission prompts. The Copilot app and CLI share the public-preview MXC sandbox; the cloud agent runs in an isolated hosted environment. Claude Code uses Seatbelt on macOS and Bubblewrap on Linux/WSL2. OpenAI Codex uses platform-native enforcement in the ChatGPT desktop app, CLI, and IDE extension. Cursor uses Seatbelt, Landlock, and WSL2. | |||||||
plugin.jsonCopilot plugin manifest |
— | Yes | Yes | Yes | — | — | — |
A Copilot plugin bundles a whole harness into one installable unit. The plugin directory carries a plugin.json manifest plus agents/, skills/, hooks.json, .mcp.json, and lsp.json. Enable plugins declaratively with the enabledPlugins field in the committed .github/copilot/settings.json, or per-user in ~/.copilot/settings.json. This is the layer that turns individual harness files into something a team can install and version as a package. | |||||||
.claude-plugin/plugin.jsonClaude plugin manifest |
— | — | — | — | Yes | — | — |
Claude Code's plugin and marketplace system. A plugin root holds .claude-plugin/plugin.json alongside skills/, agents/, hooks/, output-styles/, and .mcp.json. Settings keys include enabledPlugins, pluginConfigs, and extraKnownMarketplaces. Note the trust boundary: plugin subagents cannot use hooks, mcpServers, or permissionMode frontmatter — those fields are ignored, so installing a plugin cannot silently widen your permissions. | |||||||
copilot-setup-steps.yml.github/workflows/ |
— | — | — | Yes | — | — | — |
Provisioning for the Copilot cloud agent's ephemeral environment. A standard GitHub Actions workflow containing a single job named copilot-setup-steps, run before the agent starts: preinstall toolchains and dependencies, pick the runner, and start services. copilot-code-review.yml does the same for code review. It answers a question no instruction file can — what environment does the agent actually run in — and it is committed and reviewable like any other harness file. | |||||||
Key takeaways
AGENTS.md is the portable instruction baseline for GitHub Copilot, OpenAI Codex, and Cursor. Claude Code still reads CLAUDE.md rather than AGENTS.md, but can import that shared base with @AGENTS.md.
.agents/skills/ is the broadest shared skill path across the selected products; GitHub Copilot, OpenAI Codex, and Cursor read it natively.
Vendors are increasingly reading each other's files. Copilot reads CLAUDE.md, GEMINI.md, .claude/rules/, .claude/skills/, and .claude/settings.json hooks. Cursor reads .claude/agents/, .codex/agents/, .claude/skills/, and .codex/skills/. Compatibility reads, not standards, are doing most of the portability work right now.
Surface splitting is useful only when the harness changes. GitHub Copilot stays split because VS Code, the app, CLI, and cloud agent have distinct configuration paths; Claude Code and OpenAI Codex local clients share their core layers.
Claude Code has the richest hook system at roughly 28 events, while GitHub Copilot, OpenAI Codex, and Cursor each expose native lifecycle hooks with different schemas. Claude Code's prompt/agent handlers and Cursor's prompt hooks are the first widely available inferential sensors — a model, rather than a script, judging the agent's work.
MCP remains fragmented, but .mcp.json is now shared by the GitHub Copilot app, GitHub Copilot CLI, and Claude Code, while .github/mcp.json provides a committed Copilot-specific path.
OS-enforced isolation is now standard for local agents — Claude Code, OpenAI Codex, and Cursor all ship it. The GitHub Copilot app and CLI keep it in opt-in preview, and Copilot in VS Code has none.
The unit of configuration is shifting from the file to the bundle. Plugins now package agents, skills, hooks, and MCP servers together, and an org-managed settings tier overrides everything a repo declares. A matrix of individual files no longer captures the whole harness on its own.
Precedence & conflicts
The matrix shows which files each tool reads. This section shows what wins when files overlap: instruction load order, user/project/managed settings layers, and merge-vs-override behavior. Many instruction files are additive; many settings are not.
Confidence: documented means official docs state the rule; partial means at least one dimension is undocumented.
GitHub Copilot partial
- Instructions: all sources merged. Personal > repository > organization, but all are sent.
- Compatibility files: VS Code reads root
AGENTS.mdandCLAUDE.md; nestedAGENTS.mdis experimental. The app inherits repository and CLI customizations; the cloud agent reads both instruction formats. - App project config: trusted
.github/github-app.ymlinstructions follow global app instructions and can also define scripts and automation. - Path-scoped
*.instructions.md: merges with repo-wide.excludeAgentfrontmatter can opt out per surface (code-review,cloud-agent). - Settings: VS Code workspace > user (standard VS Code precedence).
- CLI MCP: closer
.mcp.jsonfiles beat broader files;.mcp.jsonbeats.github/mcp.jsonin the same directory, and project definitions beat user config. - Local sandbox: the app and CLI use MXC sandboxing in public preview, off by default, with enterprise enforcement available.
- Org-managed:
copilot/managed-settings.jsonin a.github-privaterepo (or an MDM policy path) overrides everything below it, includingpermissions.disableBypassPermissionsModeandsandbox.enabled. Managed sandbox restrictions combine with user settings in the most restrictive direction.
Claude Code documented
- Local surfaces: the desktop app, CLI, and editor integrations read the same settings files; cloud sessions are outside this column because they load only a subset.
- Settings (high → low): managed (org policy) > CLI args >
.claude/settings.local.json>.claude/settings.json>~/.claude/settings.json. - Permissions:
denyalways beatsallowacross all scopes. Projectdenyoverrides userallow. - CLAUDE.md: walk-up from cwd, all files concatenated. Subdirectory files lazy-load.
CLAUDE.local.mdappended afterCLAUDE.md(effectively higher priority). - AGENTS.md: not read directly — recommended pattern is
@AGENTS.mdimport insideCLAUDE.md. - Hooks: user + project both fire (merge).
allowManagedHooksOnly: trueblocks user/project. Array settings concat across sources. - MCP: managed denylist always wins over allowlist;
allowManagedMcpServersOnlylocks to admin list.
OpenAI Codex documented
- Local surfaces: the ChatGPT desktop app, CLI, and IDE extension share the local agent configuration model; CLI-only flags remain the highest-precedence one-off override.
- Settings (high → low): CLI flags and
--configoverrides > trusted project.codex/config.tomlfiles (closest wins) > selected profile >~/.codex/config.toml> system config > built-in defaults. - AGENTS.md: global guidance loads first, then project files from root down to cwd. Files closer to cwd appear later in the combined prompt and override earlier guidance.
AGENTS.override.mdbeats regular files in the same directory. - Hooks: hooks are enabled by default, use the canonical
[features].hookskey, and can come fromhooks.jsonor inline[hooks]tables in active config layers. Higher-precedence config layers do not replace lower-precedence hooks; all matching hooks run. Project-local hooks require the project.codex/layer to be trusted. - MCP per-tool approval:
default_tools_approval_modeon the server, with[mcp_servers.NAME.tools.X]overrides per tool — explicit override. - Permissions: approval policy controls prompting; named profiles (
:read-only,:workspace,:danger-full-access, or custom) control filesystem and network boundaries. - CA certs:
CODEX_CA_CERTIFICATE>SSL_CERT_FILE> system roots.
Cursor documented
- Rules (high → low): Team Rules > Project Rules (
.cursor/rules/) > User Rules. Conflicts resolved earliest-wins. - AGENTS.md: nested files combine with parent-dir; deeper (more specific) instructions take precedence.
- Team Rule enforcement: admin can mark a Team Rule "Enforce" so users cannot disable it.
- Hooks: project
.cursor/hooks.jsonand user~/.cursor/hooks.jsonboth load; enterprise team and system tiers can also distribute hooks. - Custom Modes: not a config file — any skill can be pinned as a persistent mode with Option/Alt+Enter.
- Subagents:
.cursor/agents/beats.claude/agents/and.codex/agents/on name conflicts; project scope beats user scope. - User Rules scope: Agent (Chat) only. Not applied to Inline Edit (Cmd/Ctrl+K) or Cursor Tab.
- MCP: project, user, and team-distributed tiers are available; same-name conflict behavior remains undocumented.
Sources & methodology
Every support state was re-checked against primary product documentation and official repositories on August 26, 2026. “Fallback” includes compatibility discovery or guided import; “partial” covers preview, EAP, disabled-by-default, or surface-specific behavior.