Harness Notes

JSON

Locations

5 records · Updated 2026-10-15

Where each harness looks for definitions, grouped by scope. Numbers (#) come from the source research; the Order row says what they mean. Paths are documented by the vendor unless marked source-confirmed or observed in a probe.

Skills

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

    Scan current directory, then each parent to $REPO_ROOT

  • .claude/skills

    Recursive discovery

  • .agents/skills
    Ignored · Observed in probe
  • .agents/skills
    Portable
  • .cursor/skills
    Native
  • .claude/skills
    Compatibility
  • .codex/skills
    Compatibility
  • .claude/skills
    #3 · Compatibility · Source-confirmed

    Ancestors from farthest to nearest; native probe also found a skill above the git root

  • .agents/skills
    #5 · Portable · Source-confirmed

    Ancestors from farthest to nearest; native probe also found a skill above the git root

  • .opencode/skills
    #7 · Source-confirmed

    Config ancestors from farthest to nearest; pinned source walks to filesystem root

  • .pi/skills
    Native
  • .agents/skills
    Portable

    Walk ancestors to repository root, or filesystem root outside git

User
  • $HOME/.agents/skills
    #2 · Preferred
  • $CODEX_HOME/skills
    Compatibility · Deprecated · Source-confirmed

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

  • ~/.claude/skills
  • ~/.agents/skills
    Ignored · Observed in probe
  • ~/.agents/skills
    Portable
  • ~/.cursor/skills
    Native
  • ~/.claude/skills
    Compatibility
  • ~/.codex/skills
    Compatibility
  • ~/.claude/skills
    #2 · Compatibility · Source-confirmed
  • ~/.agents/skills
    #4 · Portable · Source-confirmed
  • ~/.config/opencode/skills
    #6 · Source-confirmed

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

  • ~/.pi/agent/skills
    Native
  • ~/.agents/skills
    Portable
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 · Source-confirmed
—
Configured or per run———
  • <config-document>#skills[]
    #8 · Source-confirmed

    Explicit directories or HTTP catalogs, in config entry and array order

    Local explicit sources were probed in both array orders; HTTP catalogs were source-inspected only.

  • <settings skill paths>
  • <path passed by --skill>
Which skills are visibleEvery definition stays visibleEvery definition stays visibleEvery definition stays visibleOne definition per ID survivesEvery definition stays visible
When names collide
Same-named definitions both appear
Namespaced when plugin; otherwise documented separately
Not established
Later source wins by id
Not established
Order
  • Docs list order: Numbers follow the documentation listing; runtime scan order is not established
  • Scan order: Not established
  • Not established
  • Not established
  • Priority: Later source wins by id (numbered lowest to highest priority)
  • 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

Reviewed @opencode/cli (2.x) 2.0.20

Primary reference

pi coding agent documentation; paths documented unless marked

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

OpenCode · notes and evidence
  • Pinned V2.0.20 tag 84c9be93a56304a108f1a22df0c5d62c26d5b6ca and published @opencode/cli-darwin-arm64 2.0.20; distinct from opencode-ai 1.x and the earlier dev branch snapshot.
  • IDs derive from the containing directory or a source-root Markdown filename. Frontmatter name is a display label; equal names with different IDs coexist.
  • Source loops and sorted file loops are sequential. Later valid definitions replace earlier entries by ID; observed selections stayed stable across unchanged fixtures and file-size perturbations.
  • Order is low to high duplicate-ID precedence for this version, unlike the unproven root order in the 1.18.18 contract.
  • Within one source, files are sorted before loading; directory root-probe/SKILL.md replaced flat root-probe.md in the native probe.
  • Exact repeated source definitions are deduplicated at first registration; repeating a registered directory in explicit config does not raise its precedence.
  • No duplicate warnings were observed in these probes; neither pinned loader emits a duplicate warning. Warning absence is not proof that duplicate instances are absent.
  • GET /api/skill returns registered entries with id, name and path; its first response can precede plugin activation. Probe waits for skill plugins to be active and three identical inventory snapshots.
  • Native inventory does not prove model advertisement or invocation. V2 advertises permitted described skills unless autoinvoke is false and resolves invocation by ID, according to pinned source.
  • Cross-harness visibility persists; installer enablement intent does not prevent a compatible copy from being discovered. Removing the winning copy can expose a lower-precedence copy.
  • Sources also scan singular skill directories and configured URL catalogs; those roots were not natively probed here. Built-in override ordering is documented/source-backed, not separately probed.
  • Ancestor discovery uses fs.up without a git-root stop at this source revision; it must not inherit the v1-stable traversal claim.

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

Instructions

Where it looksCodex CLIClaude CodeCursor Agent
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.

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
Team, admin and managed—
  • <managed-policy>/CLAUDE.md
    #1

    Only when platform-specific managed path

  • <team-rules>
    #1
How instruction files combinePath applicableMerge applicableMerge applicable
When instructions conflict
More specific wins
Context guidance not enforced policy
Earlier layer wins
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)
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

No research recorded for OpenCode, 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

Hooks

Where it looksCodex CLIClaude CodeCursor Agentpi
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

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
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 order
When hooks conflict
All matching run
Decision precedence is event specific
All applicable sources
Middleware/event specific
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
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

No research recorded for OpenCode.

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

Subagents

Where it looksCodex CLICursor Agent
Project
  • .codex/agents
    #1
  • .cursor/agents
    #1
  • .claude/agents
    #2 · Compatibility
  • .codex/agents
    #3 · Compatibility
User
  • ~/.codex/agents
    #2
  • ~/.cursor/agents
    #4
  • ~/.claude/agents
    #5 · Compatibility
  • ~/.codex/agents
    #6 · Compatibility
Built in
  • <codex-built-in-agents>
    #3
—
Which definitions are visibleName precedenceName precedence
When names collide
Custom name overrides built in
First precedence wins
Order
  • Priority: Project before user before built in
  • Priority: Project before user native before compatibility (numbered highest to lowest priority)
Recorded from

Codex CLI documentation; paths documented unless marked

Primary reference

Cursor Agent CLI documentation; paths documented unless marked

Primary reference

No research recorded for Claude Code, OpenCode, 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

Plugins

Where it looksCodex CLIClaude CodeCursor Agentpi
Project———
  • .pi/extensions
    Auto discovered
User
  • <personal-plugin-installation>
  • ~/.claude/plugins
    Installed plugin state
  • ~/.cursor/plugins/local
    Local development
  • ~/.pi/agent/extensions
    Auto discovered
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 order
When names collide
Namespaced components
Plugin components namespaced
Not established
Component specific
Order
  • 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

No research recorded for OpenCode.

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

MCP servers

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

    Only when project trusted

User
  • ~/.claude.json#mcpServers
  • ~/.claude/settings.json#mcpServers
    Ignored · Observed in probe

    No evidence establishes that this location was supported previously.

    The version at which this behavior began is unknown.

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

Claude Code documentation; paths documented unless marked

Primary reference

Reviewed pi coding agent 0.99.1

Primary reference

No research recorded for Codex CLI, Cursor Agent, OpenCode.

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