---
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`.

## Reference artifacts

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