Skip to content
nexus-agents

Agent Harness Compatibility Matrix

This doc surveys the agent-config standards across the agentic-coding harness ecosystem and records how nexus-agents reaches each. AGENTS.md is the canonical surface (per #2805, choosing option B of #2764). Every other harness file in this repo is a thin redirect.

Why federate on AGENTS.md

AGENTS.md is the convergence point. As of Q2 2026 it has explicit support in:

  • OpenAI Codex CLI (codex command)
  • Anthropic Claude Code (via fallback when CLAUDE.md is absent)
  • Cursor (since v0.45 — picked up via .cursor/rules/ or direct AGENTS.md discovery)
  • Windsurf (via Cascade context discovery)
  • Aider (added in v0.69+)
  • Cline / Roo Code (project-context discovery)
  • Continue (rule sources can point at AGENTS.md)
  • Gemini CLI (reads GEMINI.md; context.fileName can point directly at AGENTS.md)
  • Goose (project conventions discovery)
  • OpenCode (opencode.json instructions can reference AGENTS.md)

Maintaining one document with thin shims into each harness gives full coverage for ~30 LOC of shims vs. ~6 KLOC of duplicated content if each harness’s file were independent.

What each harness discovers

Harness Discovery file(s) Discovery scope Loading model Native instruction format
Anthropic Claude Code CLAUDE.md (primary — generated from AGENTS.md + a Claude overlay, #3446) Project root + walking up to $HOME Auto-loaded into every session’s system prompt Markdown with optional <system-reminder> tags
Google Gemini CLI GEMINI.md (redirect), or context.fileName: AGENTS.md Project root + global at ~/.gemini/GEMINI.md Auto-loaded as context at session start Markdown
OpenAI Codex CLI AGENTS.md (canonical, since launch) Project root + global at ~/.codex/AGENTS.md Auto-loaded at session start Markdown
Cursor .cursor/rules/*.mdc, .cursorrules (legacy), AGENTS.md Project root Rule files matched by globs + description; AGENTS.md loaded as project context MDC (Cursor’s markdown-with-frontmatter) or plain markdown
Windsurf .windsurfrules, .windsurf/rules/*.md, AGENTS.md Project root Cascade indexes all rule sources Markdown
Aider .aider.conf.yml (config), CONVENTIONS.md (content), AGENTS.md Project root read: [...] in conf points at content files YAML config; markdown content
Cline / Roo Code .clinerules/*, AGENTS.md Project root Loaded into Cline’s system message Markdown
Continue .continue/rules/*.md, .continue/config.json Project root + global at ~/.continue/ Rule files referenced from config; AGENTS.md works as a rule source Markdown
Goose recipe.yaml (per-recipe), project conventions in markdown, AGENTS.md Per-recipe + project root Recipe-scoped; project conventions discovered at session start YAML + markdown
OpenCode opencode.json (config + instructions array), referenced markdown, AGENTS.md Project root + global at ~/.config/opencode/ instructions field can name AGENTS.md directly JSON config; markdown content

What nexus-agents ships today

File Role Status
AGENTS.md Canonical surface; harness-neutral Source of truth
CLAUDE.md Claude Code-specific entry point with plugin/skill integration details Generated from AGENTS.md’s agnostic body + a Claude overlay (#3446)
skills/index.yaml + skills/*/SKILL.md Anthropic Agent Skills spec (#1828) Discovered by harnesses that support skills; documented from AGENTS.md
.rules/*.md Per-rule files auto-loaded by Claude Code; referenced from AGENTS.md Kept; AGENTS.md indexes them
docs/ENTRYPOINTS.md CLI + MCP tool reference Referenced from AGENTS.md

Harness redirect shims

These root/harness-config files exist as one-line redirects to AGENTS.md (added in #2805 Phase 2 + #3446 Phase 4). The Harness Alignment Drift CI gate (scripts/check-harness-alignment.ts) fails if any present file stops referencing AGENTS.md:

File Harness Content shape
.cursor/rules/agents.mdc Cursor MDC frontmatter alwaysApply: true, body redirects to AGENTS.md
.windsurf/rules/agents.md Windsurf Markdown; one-line redirect
.aider.conf.yml Aider read: [AGENTS.md, CLAUDE.md]
.continue/rules/agents.md Continue Markdown redirect
.clinerules/agents.md Cline Markdown redirect
GEMINI.md Gemini Markdown redirect (root-level; Gemini CLI reads it natively)

opencode.json and Goose recipe.yaml are project-config files with broader concerns than just instruction surfacing — those stay out of scope unless we ship an OpenCode/Goose adapter directly.

Federation invariants

When Phase 2 lands, these become invariants of the repo:

  1. AGENTS.md is the only place content is authored. Shim files MUST point at AGENTS.md, not duplicate content.
  2. nexus-agents doctor reports alignment. Project-level doctor walks the discovery files and reports whether each one resolves back to AGENTS.md. Phase 3 of #2805.
  3. Drift detection. Upstream changes to AGENTS.md community conventions or per-harness rule syntax get flagged via a periodic check (Phase 5).
  4. No content duplication ever. PRs that duplicate AGENTS.md content into a harness file are refactored to redirects before merge.

References

See also