---
title: Providers
description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemini, and Codex adapters.'
---

# Providers

## Provider Quick Browse

=== "Claude"

    - Project: `.agents/skills` -> `.claude/skills`, `.agents/agents` -> `.claude/agents`, `.agents/rules` -> `.claude/rules`
    - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
    - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
    - Managed phase implementers and optional nested workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Agent `model`

=== "Cursor"

    - Project skills are native-read from `.agents/skills`; agents and rules still sync to `.cursor/agents` and `.cursor/rules`
    - User skills are native-read from `~/.agents/skills`; agents still sync to `~/.cursor/agents`
    - `.cursor/skills` and `~/.cursor/skills` remain supported Cursor-only extension and adoption surfaces. OAT does not generate skill views there.
    - Interactive `oat init` and `oat status` ask for an individual disposition for each unresolved Cursor-local skill: adopt it into `.agents/skills` or keep it Cursor-only and remember the exact path in sync config
    - Keep-local is blocked when a canonical skill has the same name because Cursor does not document a safe duplicate-resolution order
    - During upgrades, OAT removes only verified clean legacy managed skill views. Changed or replaced views are preserved, detached from manifest ownership, and offered for migration.
    - Sync materializes pinned Markdown definitions for both `oat-phase-implementer` and `oat-reviewer`. Each generated name keeps the configured flat ladder ID, while an explicit verified mapping writes the separate bracket-form frontmatter model. OAT never derives one form from the other.
    - Generated definitions carry `supported-catalogue`, `project-config`, or `user-config` ownership. Project and supported output lives in the tracked `.cursor/agents` view; user-owned output lives under `~/.cursor/agents`. Cleanup reconciles only the applicable owner.
    - Managed dispatch requires `providers.cursor.dispatchArgs.variant` and launches that exact resolver-selected native agent type first. Skills do not pass a Task-level model argument or normalize Cursor model strings.
    - Cursor may silently fallback when a definition pin cannot be honored. Variant acceptance therefore establishes launcher-owned `configured` provenance only; runtime identity remains `not-reported` unless independently observed.
    - `oat doctor` checks whether each flat ID is still present in the current Cursor catalogue and reports availability drift. Catalogue availability is diagnostic and does not prove that a definition-level bracket pin ran as configured.
    - Rule files render as `.cursor/rules/*.mdc`

=== "Copilot"

    - Project: `.agents/skills` -> `.github/skills`, `.agents/agents` -> `.github/agents`, `.agents/rules` -> `.github/instructions`
    - User: `~/.agents/skills` -> `~/.copilot/skills`, `~/.agents/agents` -> `~/.copilot/agents`
    - Rule files render as `.github/instructions/*.instructions.md`
    - Canonical always-on rules render with `applyTo: "**"` so Copilot activates them repo-wide; provider rules with exactly `applyTo: "**"` adopt back to `activation: always`
    - Comma-containing globs are not supported for Copilot rule sync because Copilot uses a comma-separated `applyTo` field

=== "Gemini"

    - Project: native-read canonical mappings (`.agents/skills` and `.agents/agents`)
    - User: native-read canonical mappings (`~/.agents/skills` and `~/.agents/agents`)
    - Gemini provider sync does not mirror to a provider-specific directory because canonical paths are read directly

=== "Codex"

    - Skills are native-read from `.agents/skills` (no mirrored sync action for skill mappings)
    - Agents are native-read from `.agents/agents` for canonical source-of-truth workflows
    - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
      - `.codex/agents/<role>.toml`
      - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
    - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
    - Project sync writes and maintains the version-controlled supported catalogue: Luna and Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and `max`, for both `oat-phase-implementer` and `oat-reviewer` (26 pinned variants). Sync writes files; it does not create a Git commit.
    - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.
    - User sync loads only the bundled canonical `oat-phase-implementer` and `oat-reviewer` definitions needed to expand user-config targets. It does not enable general user-agent mirroring, and it refuses stale user-role cleanup if either managed definition is unavailable.
    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership. Cleanup removes stale entries only for the owner being reconciled and preserves other scopes plus unrelated Codex entries.
    - All project-generated Codex variants and config registrations are repository-owned, version-controlled output and are never auto-ignored by OAT. User-config output remains under `~/.codex`.
    - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
    - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
    - Sync-time materialization is best effort; managed workflow correctness uses exact registered roles or a fresh child pinned to the resolved model plus reasoning effort with canonical role instructions, and does not require provider restart/hot reload
    - Codex `max` is a first-class dispatch effort. It is present only for the Sol family in the committed supported catalogue, for both implementer and reviewer roles.
    - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
    - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; sync and direct materialization still merge that capability floor without lowering a higher target value.
    - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
    - Missing depth and explicit depth `1` are sufficient for default phase execution. Invalid values or values below `1` block managed implementation preflight. `oat doctor` explains when depth `2` optional nesting is available.
    - The phase implementer directly executes its planned tasks from one Phase Scope, preserves one bounded commit per task, and returns phase-wide verification. It does not dispatch the phase reviewer.

## Managed dispatch views

Reusable ordered candidate ladders live in `workflow.dispatchCeiling.providers`.
The project or phase named ceiling is only a maximum over those candidates; it
does not select one permanent model family for the project.

Adopt the complete ladder into an explicit owning config scope before sync:

```bash
oat config adopt dispatch-matrix --shared
oat config adopt dispatch-matrix --local
oat config adopt dispatch-matrix --user
```

Project-config candidates materialize into the tracked, version-controlled
project `.codex` and `.cursor` views. User-config candidates materialize under
`~/.codex` and `~/.cursor`. OAT does not auto-ignore project output or create
its Git commit; the team owns that repository change.

At implementation time, the root passes the recorded named maximum through
invocation-only `--ceiling-tier`, resolves one exact candidate per phase, and
dispatches one phase implementer. Codex first attempts the resolver-returned
materialized role as the native `agent_type`. The launcher records the target,
model axis, and effort axis from that resolved payload; child self-report is not
provenance and cannot replace those values.
Only an explicit pre-start native role-selection rejection permits another
target-preserving route. An accepted child, including one that later returns
`BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
Claude binds the exact model argument described above. Cursor launches the
exact native variant. A missing or unselectable managed target blocks rather
than falling back to the root target or a base role.

## Scope rules

- Project scope: skills + agents + rules
- User scope: skills, plus the two bundled managed Codex and Cursor role definitions used only for user-owned target expansion (provider mappings vary by adapter)
- Rules are project-scoped only in this release
- Codex user-scope sync materializes user-config custom roles under `~/.codex`; project-config and supported-catalogue output remains project-scoped and version controlled
- Cursor user-scope sync materializes user-config variants under `~/.cursor/agents`; project-config and supported-catalogue output remains project-scoped and version controlled

## Adoption model

- Stray adoption is available in `oat init` and `oat status`.
- Adoption reconciles canonical plus the adopted provider first.
- Native-read Cursor skill adoption moves the provider-local skill into `.agents/skills` without recreating a `.cursor/skills` view or manifest entry.
- Choosing Keep Cursor-only leaves the skill in place and records its exact normalized path in the project or user sync config.
- Rule adoption normalizes provider filenames back to canonical `.agents/rules/*.md` entries before cross-provider fanout.
- Cross-provider fanout is explicit via `oat sync --scope all`.

## Provider mutation safety

The generic sync engine validates provider destinations for every operation that
creates or updates a symlink, creates or updates a copy, or removes a managed
provider path. The same guard applies across provider adapters; it is not
Claude-specific.

Validation runs at three boundaries:

1. During planning, before a provider operation is classified.
2. Across the complete mutating plan before apply starts, so an already-unsafe
   later entry cannot allow earlier provider or manifest mutations.
3. Immediately before each entry's first filesystem mutation, so ancestry that
   changes after preflight fails closed.

A mutation is refused when its destination escapes the sync scope, equals the
scope root, or has any existing parent that is a symbolic link or not a
directory. The final managed destination is excluded from the ancestry walk, so
an existing managed symlink can still be updated or removed normally.

Whole-plan preflight refusal leaves provider paths, canonical content, external
symlink targets, and manifest state unchanged. If ancestry changes after
preflight, the affected entry fails before its first removal or write and does
not gain manifest ownership. OAT does not traverse, unlink, or rewrite the
unsafe parent.

## Reference artifacts

- `.oat/projects/<scope>/<project>/spec.md` (FR5)
- `packages/cli/src/providers/**`
- `packages/cli/src/providers/shared/adapter.utils.ts`
