Providers

Workloom models AI tool providers explicitly because they're fundamentally different. A one-size-fits-all approach would compromise trust, privacy, and usability.

Why Model Providers Explicitly?

Each AI tool has:

• Different file locations where configuration lives
• Different precedence models (layering, nesting, overrides)
• Different write patterns (auto-generated, committed, user-local, extension-based)
• Different trust gates and audit requirements
• Different capability sets

Pretending they're all the same would either weaken security or break functionality. Instead, Workloom makes each provider a first-class citizen.

Provider Overview

Claude

Status (Phase 1): Renderer implemented

Claude uses a layered settings hierarchy:

.claude/settings.json          ← Editor settings, keybindings
CLAUDE.md                       ← Session instructions
.claude/hooks/**               ← Lifecycle hooks
.claude/skills/**              ← Task definitions
.claude/agents/**              ← Agent configurations

Precedence Model: Settings are merged bottom-up: defaults → org → workspace → project → session

Trust Gates:

• CLAUDE.md instructions — can be generated_local
• Skills and agents — require manual_review or approval_required
• Hooks — require explicit approval_required

Workloom Renders:

• .claude/settings.json from package provider configs
• CLAUDE.md from instructions
• .claude/skills/ from skill assets
• .claude/hooks/ from hook assets

Codex

Status (Phase 1): Renderer implemented

Codex uses nested AGENTS.md files:

AGENTS.md                       ← Root (merged from all sources)
.codex/config.toml             ← Codex settings
.codex/skills/**               ← Skill definitions
.codex/agents/**               ← Agent configurations

Precedence Model: AGENTS.md files are merged using a nested merge strategy — not simple concatenation. Each section is independently mergeable.

Trust Gates:

• AGENTS.md content — depends on asset type
• .codex/config.toml settings — requires configuration trust class
• Hooks and skills — standard trust gates apply

Workloom Renders:

• Nested merge of all AGENTS.md content
• .codex/config.toml from provider configs
• .codex/skills/ from skill assets

Gemini

Status (Phase 1): Fixtures only (Phase 5 renderer planned)

Gemini uses an extension manifest model:

~/.config/google-gemini/       ← User's local extension directory
manifest.json                   ← Extension manifest

Unique Characteristic: Workloom never writes to the user's home directory. Gemini's auto-install model means users control their own extensions. Instead, Workloom:

1. Generates the extension manifest to a staging directory
2. Provides instructions for the user to install
3. Tracks checksums to detect when users update extensions

Trust Gates:

• Extensions require explicit user approval (Gemini handles this)

Copilot

Status (Phase 1): Fixtures only (Phase 5 renderer planned)

Copilot uses a committed-only model:

.github/copilot-instructions.md     ← Organization instructions
.github/instructions/**             ← Additional instruction files

Unique Characteristic: Org policies are committed to git and enforced at the GitHub level. Developers cannot override org instructions locally.

Write Pattern: Files go into .github/ and must be committed. No local generation.

Trust Gates:

• Org instructions — require approval before commit
• Policy files — require security review

Cursor

Status (Phase 1): Fixtures only (Phase 5 renderer planned)

Cursor uses project-scoped rules:

.cursor/rules/**                ← Project-specific rules
.cursorrules                     ← Project rules (compact format)

Unique Characteristic: Rules are project-local (per editor instance). They follow .gitignore conventions — they can be committed or local.

Write Pattern: Can be generated locally or committed, depending on team policy.

Trust Gates:

• Executable rules — require approval
• Configuration rules — require manual review

Provider Capability Matrix

Capability	Claude	Codex	Gemini	Copilot	Cursor
Instructions	✓	✓	✓	✓	✓
Skills	✓	✓	—	—	—
Hooks	✓	✓	—	—	—
MCP Servers	✓	✓	—	—	—
Settings	✓	✓	✓	—	✓
Auto-Write	✓	✓	No	No	✓
Committed Model	—	—	—	✓	✓
Extension Model	—	—	✓	—	—

Provider Overrides in Assets

An asset can have provider-specific configurations:

{
  "name": "baseline-instructions",
  "type": "instruction",
  "path": "CLAUDE.md",
  "providerOverrides": {
    "codex": {
      "path": "docs/AGENTS.md",
      "mergeStrategy": "nested",
      "commentStyle": "markdown"
    },
    "cursor": {
      "path": ".cursorrules",
      "maxLength": 2000
    },
    "copilot": {
      "path": ".github/copilot-instructions.md"
    }
  }
}

Each provider can have:

• Different file paths
• Different content transformations
• Different merge strategies
• Provider-specific metadata

Phase 1 vs Phase 5 Status

Provider	Phase 1	Phase 5
Claude	✓ Renderer implemented	✓ Complete
Codex	✓ Renderer implemented	✓ Complete
Gemini	Fixtures only	✓ Renderer implemented
Copilot	Fixtures only	✓ Renderer implemented
Cursor	Fixtures only	✓ Renderer implemented

Phase 1 focuses on Claude and Codex because they have the richest feature sets and largest user bases. Phase 5 will complete the set.

Provider Selection Per Target

Each target declares which providers it supports:

{
  "id": "root",
  "path": ".",
  "providers": ["claude", "codex"],
  "packages": [...]
}

Workloom only renders files for the providers in this list. If a target specifies ["claude"], no Codex files are generated, even if the package contains Codex assets.

This lets monorepos use different tools in different parts:

• Root: Codex (for automation)
• Frontend: Claude + Cursor (for IDE augmentation)
• Backend: Claude + Codex (for development + automation)

What's Next

Now that you understand how providers work, let's explore trust and privacy — Workloom's enterprise-grade governance model.

Custom Providers

In Phase 3+, Workloom will support custom provider plugins, allowing teams to render to proprietary or internal AI tools. For now, the five providers above are supported.