Harness Notes
AboutJSON

Locations

Updated 2026-10-15

On this page

Where each harness looks for definitions, grouped by scope. Numbers (#) give each path's place in the order; the Order row says what they mean. Paths are documented by the vendor unless marked undocumented.

Skills

Where it looksCodex CLIClaude CodeCursor AgentpiOpenCode
Project
  • $CWD/.agents/skills
    #1

    Scan current directory, then each parent to $REPO_ROOT

  • .claude/skills

    Recursive discovery

  • .agents/skills
    Ignored, Undocumented
  • .agents/skills
    Portable
  • .cursor/skills
    Native
  • .claude/skills
    Compatibility
  • .codex/skills
    Compatibility
  • .pi/skills
    Native
  • .agents/skills
    Portable

    Walk ancestors to repository root, or filesystem root outside git

  • .claude/skills
    #3, Compatibility, Undocumented

    Compatibility ancestors from farthest toward current directory

  • .agents/skills
    #5, Portable, Undocumented

    Compatibility ancestors from farthest toward current directory

  • .opencode/skills
    #7, Undocumented

    Project directories from project root toward current directory

User
  • $HOME/.agents/skills
    #2, Preferred
  • $CODEX_HOME/skills
    Compatibility, Deprecated, Undocumented

    Defaults to ~/.codex/skills; follows CODEX_HOME when overridden.

  • ~/.claude/skills
  • ~/.agents/skills
    Ignored, Undocumented
  • ~/.agents/skills
    Portable
  • ~/.cursor/skills
    Native
  • ~/.claude/skills
    Compatibility
  • ~/.codex/skills
    Compatibility
  • ~/.pi/agent/skills
    Native
  • ~/.agents/skills
    Portable
  • ~/.claude/skills
    #2, Compatibility, Undocumented
  • ~/.agents/skills
    #4, Portable, Undocumented
  • ~/.config/opencode/skills
    #6, Undocumented

    Default XDG_CONFIG_HOME; actual native root is $XDG_CONFIG_HOME/opencode/skills.

Team, admin and managed
  • /etc/codex/skills
    #3
  • <managed-skill-directories>
———
Plugins and packages
  • <enabled-plugin>/skills
    #5
  • <enabled-plugin>/skills
  • <enabled-plugin>/skills
  • <package skill paths>
—
Built in
  • <codex-bundled-skills>
    #4
———
  • <built-in-skills>
    #1, Built in, Undocumented
Configured or per run———
  • <settings skill paths>
  • <path passed by --skill>
  • <config-document>#skills[]
    #8, Undocumented

    Compatibility ancestors from farthest toward current directory

    Confirmed for local directories in either order; for HTTP catalogs this comes from the code only.

Which skills are visibleEvery definition stays visibleEvery definition stays visibleEvery definition stays visibleEvery definition stays visibleOne definition per ID survives
When names collide
Same-named definitions both appear
Namespaced when plugin; otherwise documented separately
Not established
Not established
Later source wins by id
Order
  • Docs list order: Numbers follow the documentation listing; runtime scan order is not established
  • Scan order: Not established
  • Not established
  • Not established
  • Not established
  • Priority: Later source wins by id (numbered lowest to highest priority)
Recorded from

Codex CLI documentation; paths documented unless marked

Primary reference

Claude Code documentation; paths documented unless marked

Primary reference

Cursor Agent CLI documentation; paths documented unless marked

Primary reference

pi coding agent documentation; paths documented unless marked

Primary reference

Reviewed @opencode/cli (2.x) 2.0.29

Primary reference
Codex CLI, notes and evidence
  • Two skills with the same name are not merged; both may appear.
  • Symlinked skill directories are followed.
  • Numbered locations reflect the documentation listing; the unnumbered deprecated root is source-confirmed, not a documented precedence position.
  • Reclassified 2026-10-14: v1 orderStatus was "documented-scan-order". The v1 notes state: "Numbered locations reflect the documentation listing; the unnumbered deprecated root is source-confirmed, not a documented precedence position." Positions are retained as listing only; runtime scan order is not established.

Evidence

Claude Code, notes and evidence
  • Claude Code 2.1.300 did not automatically discover project .agents/skills or user ~/.agents/skills in the 2026-10-15 isolated startup-inventory probe. Both .claude/skills controls were discovered; moving the identical .agents fixtures into .claude/skills made them appear. Invocation was not tested because the isolated home had no login.
  • The documentation does not promise that this display order is duplicate-name precedence.

Evidence

Cursor Agent, notes and evidence
  • Discovery is recursive.
  • User roots do not transfer to cloud agents or remote workers.
  • The documentation lists roots but does not establish duplicate-name precedence.

Evidence

pi, notes and evidence
  • --no-skills disables discovery but does not cancel explicit --skill paths.
  • Pin pi version before relying on root Markdown discovery or duplicate precedence.

Evidence

OpenCode, notes and evidence
  • Released 2.0.29 source/documentation review; this is not a rerun of the retained 2.0.20 native probe.
  • Later registered sources replace earlier definitions by path-derived ID; frontmatter name is a display label.
  • Native config scans also accept the singular skill directory; explicit sources may be local directories or HTTP catalogs.

Evidence

Instructions

Where it looksCodex CLIClaude CodeCursor AgentOpenCode
Project
  • <repo-to-cwd>/{AGENTS.override.md,AGENTS.md,<configured-fallback>}
    #2

    Only when at most one non-empty file per directory; override then base then fallback

  • <cwd-and-ancestors>/{CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md}
    #4

    Only when applicable instructionFiles mode

  • <cwd-and-ancestors>/{AGENTS.md,.claude/AGENTS.md}
    #5

    Only when Claude Code 2.1.277+; enabled built-in agents-md; fallback or combined mode

  • <project>/.claude/rules/**/*.md
    #6

    Only when unscoped rules load at launch; rules with paths frontmatter load when Claude works with a matching file; skipped when project is excluded from --setting-sources

  • <subdirectory>/{CLAUDE.md,CLAUDE.local.md,AGENTS.md}

    Only when loaded on demand; AGENTS.md requires applicable mode and local fallback check

  • .cursor/rules/**/*.mdc
    #2
  • <project-or-subdirectory>/AGENTS.md
    #2

    AGENTS.md is documented as a project instruction source; its placement in the project precedence layer is an inference.

  • AGENTS.md

    Current workspace toward home; outside home, stop at project root

  • <nested-directory>/AGENTS.md

    Added when a file is read or directory is listed

User
  • <CODEX_HOME>/{AGENTS.override.md,AGENTS.md}
    #1

    Only when first non-empty file wins

  • ~/.claude/CLAUDE.md
    #2

    Only when unless excluded by instructionFiles mode

  • ~/.claude/rules/**/*.md
    #3

    Only when unscoped rules load at launch; rules with paths frontmatter load when Claude works with a matching file

  • <user-rules>
    #3
  • ~/.config/opencode/AGENTS.md
Team, admin and managed—
  • <managed-policy>/CLAUDE.md
    #1

    Only when platform-specific managed path

  • <team-rules>
    #1
—
Configured or per run———
  • $OPENCODE_CONFIG_DIR/AGENTS.md
How instruction files combinePath applicableMerge applicableMerge applicableCombine
When instructions conflict
More specific wins
Context guidance not enforced policy
Earlier layer wins
No conflict resolution
Order
  • Load order: Broad to specific
  • Load order: Managed then user then project root to working directory
  • Priority: Team before project before user (numbered highest to lowest priority)
  • Load order: Global then current directory toward ancestor boundary
Recorded from

Codex CLI documentation; paths documented unless marked

Primary reference

Claude Code documentation; paths documented unless marked

Primary reference

Cursor Agent CLI documentation; paths documented unless marked

Primary reference

Reviewed @opencode/cli (2.x) 2.0.29

Primary reference

No research recorded for pi.

Codex CLI, notes and evidence
  • Instruction discovery follows the working path and stops at the current directory; it is distinct from skill discovery.
  • Files compose root-to-current-directory until the configured combined-byte limit is reached.

Evidence

Claude Code, notes and evidence
  • See the Claude instruction contract for structured modes, exclusions, and version caveats.
  • Reclassified 2026-10-15 from the documented load order at code.claude.com/docs/en/memory#how-claude-md-files-load.

Evidence

Cursor Agent, notes and evidence
  • Project rules may activate always, by glob, by relevance, or manually.

Evidence

OpenCode, notes and evidence
  • V2 recognizes AGENTS.md only; CLAUDE.md fallback is not supported.
  • OPENCODE_DISABLE_PROJECT_CONFIG=1 skips project discovery while retaining the global file.
  • Loaded files combine without harness conflict resolution.
  • Instruction order does not establish a winning conflicting instruction.

Evidence

Hooks

Where it looksCodex CLIClaude CodeCursor AgentpiOpenCode
Project
  • <repo>/.codex/hooks.json

    Only when project layer is trusted

  • <repo>/.codex/config.toml#[hooks]

    Only when project layer is trusted

  • .claude/settings.json#hooks
  • .claude/settings.local.json#hooks
  • <project>/.cursor/hooks.json
  • .pi/extensions/*.ts

    Only when project trusted

  • .pi/extensions/*/index.ts

    Only when project trusted

  • .opencode/plugins
    Undocumented
  • opencode.json(c)#plugins
    Undocumented
User
  • ~/.codex/hooks.json
  • ~/.codex/config.toml#[hooks]
  • ~/.claude/settings.json#hooks
  • ~/.cursor/hooks.json

    Only when local agents only

  • ~/.pi/agent/extensions/*.ts
  • ~/.pi/agent/extensions/*/index.ts
  • ~/.config/opencode/plugins
    Undocumented
Team, admin and managed
  • <system-or-managed>/requirements.toml
  • <managed-policy-settings>
  • <enterprise-managed-hooks>
  • <team-distributed-hooks>
——
Plugins and packages
  • <enabled-plugin>/hooks/hooks.json

    Only when hook definition is trusted

  • <enabled-plugin>/hooks/hooks.json
  • <enabled-plugin>/hooks
  • <package extensions>
—
Configured or per run—
  • <invoked-skill>/SKILL.md#hooks
  • <running-subagent-frontmatter>#hooks
—
  • <settings extensions>
  • <path passed by --extension/-e>
—
How hooks from several places combineMerge allMerge allMerge allExtension load orderLoad all
When hooks conflict
All matching run
Decision precedence is event specific
All applicable sources
Middleware/event specific
Not established

Handler interactions depend on hook and plugin; no global collision policy asserted.

Order
  • Run order: Matching hooks run concurrently
  • Run order: Matching handlers may run in parallel
  • Not established
  • Run order: Chained handlers run in extension load order
  • Not established
Recorded from

Codex CLI documentation; paths documented unless marked

Primary reference

Claude Code documentation; paths documented unless marked

Primary reference

Cursor Agent CLI documentation; paths documented unless marked

Primary reference

pi coding agent documentation; paths documented unless marked

Primary reference

Reviewed @opencode/cli (2.x) 2.0.29

Primary reference
Codex CLI, notes and evidence
  • All matching sources merge; higher-precedence config layers do not replace lower hook layers.
  • Matching command hooks launch concurrently, so list order is not execution order.

Evidence

Claude Code, notes and evidence
  • Hook entries merge across settings levels rather than replacing each other.
  • Matching handlers may run in parallel; event decision precedence is separate from source order.
  • allowManagedHooksOnly can exclude user, project, local, and most plugin hooks.

Evidence

Cursor Agent, notes and evidence
  • The source list is not a guaranteed handler execution order.
  • Cloud agents omit user hooks and several event types; command hooks only.
  • Working directory differs by source scope.

Evidence

pi, notes and evidence
  • Handlers that chain mutations run in extension load order; later handlers see earlier changes.
  • Project extensions cannot participate in project_trust because they load only after trust resolves.

Evidence

OpenCode, notes and evidence
  • Direct .ts/.js files and immediate package directories are discovered; configured relative entries resolve from their config file.
  • Hook handlers are plugin code, with event-specific control.

Evidence

Subagents

Where it looksCodex CLICursor AgentOpenCode
Project
  • .codex/agents
    #1
  • .cursor/agents
    #1
  • .claude/agents
    #2, Compatibility
  • .codex/agents
    #3, Compatibility
  • .opencode/agents/<name>.md
  • agents key in project config
User
  • ~/.codex/agents
    #2
  • ~/.cursor/agents
    #4
  • ~/.claude/agents
    #5, Compatibility
  • ~/.codex/agents
    #6, Compatibility
  • ~/.config/opencode/agents/<name>.md
  • agents key in global config
Built in
  • <codex-built-in-agents>
    #3
——
Which definitions are visibleName precedenceName precedenceAgent definition merge
When names collide
Custom name overrides built in
First precedence wins
Not established
Order
  • Priority: Project before user before built in
  • Priority: Project before user native before compatibility (numbered highest to lowest priority)
  • Not established
Recorded from

Codex CLI documentation; paths documented unless marked

Primary reference

Cursor Agent CLI documentation; paths documented unless marked

Primary reference

Reviewed @opencode/cli (2.x) 2.0.29

Primary reference

No research recorded for Claude Code, pi.

Codex CLI, notes and evidence
  • A custom agent with the same name as a built-in agent takes precedence.
  • Each custom agent is a standalone TOML configuration layer.

Evidence

Cursor Agent, notes and evidence
  • Project definitions take precedence over user definitions; native Cursor roots take precedence over compatibility roots for duplicate names.

Evidence

OpenCode, notes and evidence
  • The same agent roots define primary agents and subagents; mode selects their role.
  • Legacy numeric precedence metadata is not projected as a separately established scan or load sequence.

Evidence

Plugins

Where it looksCodex CLIClaude CodeCursor AgentpiOpenCode
Project———
  • .pi/extensions
    Auto discovered
  • .opencode/plugins
    Undocumented
  • opencode.json(c)#plugins
    Undocumented
User
  • <personal-plugin-installation>
  • ~/.claude/plugins
    Installed plugin state
  • ~/.cursor/plugins/local
    Local development
  • ~/.pi/agent/extensions
    Auto discovered
  • ~/.config/opencode/plugins
    Undocumented
Team, admin and managed
  • <team-marketplace-installation>
  • <marketplace-installation>
  • <installed-cursor-plugin>
——
Plugins and packages———
  • <installed npm/git package>
—
Configured or per run
  • <local-plugin-directory>
  • <directory passed to --plugin-dir>
    Development
  • <directory passed to --plugin-dir>
    Local development
  • settings.json#extensions
  • <path passed by --extension/-e>
—
Which plugins loadEnabled setEnabled setEnabled setExtension load orderLoad all
When names collide
Namespaced components
Plugin components namespaced
Not established
Component specific
Not established

Handler interactions depend on hook and plugin; no global collision policy asserted.

Order
  • Not established
  • Not established
  • Not established
  • Not established
  • Not established
Recorded from

Codex CLI documentation; paths documented unless marked

Primary reference

Claude Code documentation; paths documented unless marked

Primary reference

Cursor Agent CLI documentation; paths documented unless marked

Primary reference

pi coding agent documentation; paths documented unless marked

Primary reference

Reviewed @opencode/cli (2.x) 2.0.29

Primary reference
Codex CLI, notes and evidence
  • The public contract is installation/enabling, not a stable cache path. Do not treat an implementation cache as an authoring root.

Evidence

Claude Code, notes and evidence
  • Installed plugins may be copied into a cache; plugin code must resolve assets through ${CLAUDE_PLUGIN_ROOT}, not its authoring path.

Evidence

Cursor Agent, notes and evidence
  • Plugin-relative paths use ${PLUGIN_ROOT}; do not persist author-machine absolute paths.

Evidence

pi, notes and evidence
  • pi calls this surface extensions/packages rather than plugins.
  • Duplicate commands receive numeric suffixes in load order instead of silently replacing each other.
  • V1 labeled loading "documented-partially" but did not record a complete sequence. No complete ordering is inferred during migration.

Evidence

OpenCode, notes and evidence
  • Direct .ts/.js files and immediate package directories are discovered; configured relative entries resolve from their config file.
  • Hook handlers are plugin code, with event-specific control.

Evidence

MCP servers

Where it looksClaude CodepiOpenCode
Project
  • ~/.claude.json#projects.<cwd>.mcpServers
  • .mcp.json#mcpServers
  • .pi/mcp.json#mcpServers

    Only when project trusted

  • opencode.json(c)

    Current directory toward filesystem root

  • .opencode/opencode.json(c)

    Applicable ancestor configuration directories

User
  • ~/.claude.json#mcpServers
  • ~/.claude/settings.json#mcpServers
    Ignored, Undocumented

    No evidence establishes that this location was supported previously.

    The version at which this behavior began is unknown.

  • ~/.pi/agent/mcp.json#mcpServers
  • ~/.config/opencode/opencode.json(c)
How server configs combineScope precedenceProject over globalWhole server replacement
Same server name in two places
Higher scope precedence wins
Project server name replaces global
Higher precedence config replaces server object
Order
  • Not established
  • Priority: Project server name replaces global
  • Not established
Recorded from

Claude Code documentation; paths documented unless marked

Primary reference

Reviewed pi coding agent 0.99.1

Primary reference

Reviewed @opencode/cli (2.x) 2.0.29

Primary reference

No research recorded for Codex CLI, Cursor Agent.

Claude Code, notes and evidence
  • V1 records scope precedence but no scope sequence. Its collision rule is retained separately; no exact ordering is inferred.

Evidence

  • Claude Code MCP, first-party-docs, 2026-10-15
  • Claude Code 2.1.251 MCP settings discovery observation, live-observation, 2026-09-08
pi, notes and evidence
  • Applies to built-in MCP in 0.99.1. An extension registering /mcp replaces built-in session discovery; SDK sessions must opt in.

Evidence

OpenCode, notes and evidence
  • Managed system configuration and macOS MDM settings have higher priority.
  • A same-name server object is replaced as a whole; fields do not merge.
  • Project servers connect without a trust prompt; managed integration policies can block activation.

Evidence