wikis / T3 Code / wiki / concepts / providers.md view as markdown report a mistake

Definition

A provider is the agent runtime that does the actual work behind a T3 Code thread — Codex, Claude Code, Cursor, Grok Build, or OpenCode. T3 Code's orchestration layer is deliberately provider-agnostic: it does not know or care which provider is behind a given thread. Each provider is wired into T3 Code through a driver plus an adapter that translate that provider's native CLI protocol into T3 Code's internal command/event model.

How It Works

builtInDrivers.ts exports BUILT_IN_DRIVERS with five entries:

Each driver declares a driverKind, a configSchema, and a create function that builds an adapter in a child scope. Adapter implementations (CodexAdapter.ts, ClaudeAdapter.ts, etc.) live beside their drivers and conform to a shared ProviderAdapter interface.

Two registries separate configuration from live processes: ProviderInstanceRegistry keys configured instances by ProviderInstanceId (looking up the driver by driverKind, decoding the instance's config with that driver's schema, and calling driver.create in a child scope), while ProviderAdapterRegistry resolves an instance ID to its live adapter. ProviderService sits on top of both, routing session and turn operations by thread rather than by agent — so callers name a thread, and the provider behind it is an implementation detail. Adding a new driver only means writing the driver plus its adapter and registering it in BUILT_IN_DRIVERS; no orchestration, contract, or client change is required for the common case.

Clients never call a provider directly. They dispatch orchestration commands over the RPC method orchestration.dispatchCommand — the client-facing provider commands are thread.turn.start, thread.turn.interrupt, thread.approval.respond, thread.user-input.respond, thread.checkpoint.revert, thread.session.stop, and the mode setters thread.runtime-mode.set / thread.interaction-mode.set (the runtime-mode setter underlies permission modes). The server persists an event for the command, and a server-side reactor performs the actual provider call; provider output comes back as internal commands (thread.message.assistant.delta, thread.session.set, etc.) that clients observe via orchestration.subscribeThread.

Provider work flows through three queue-backed workers, each built with makeDrainableWorker and exposing drain for deterministic test synchronization: ProviderRuntimeIngestion (consumes provider runtime streams and emits orchestration commands), ProviderCommandReactor (reacts to orchestration intent events and dispatches provider calls), and CheckpointReactor (captures workspace checkpoints on turn start/completion and performs reverts). A thread in buffered assistant delivery mode accumulates assistant text instead of streaming every delta; the buffer spills as one delta if it would exceed MAX_BUFFERED_ASSISTANT_CHARS (24,000 characters), and also flushes at interaction boundaries (an approval opening, or user input being requested).

Per-provider setup

Install-and-login basics for each provider (see install and getting started for the full table): Codex CLI + codex login; Claude Code + claude auth login; Cursor CLI (binary cursor-agent) + agent login; Grok Build CLI + grok login; OpenCode + opencode auth login. Each provider CLI must be on the T3 Code server's PATH, or have an explicit binary path configured in Settings.

Claude and Codex both support multi-account setups in T3 Code:

• Claude (provider claude code): a single account uses the default provider with an empty CLAUDE_CONFIG_DIR path. Multiple accounts (e.g. work and personal) each get a dedicated CLAUDE_CONFIG_DIR — set via CLAUDE_CONFIG_DIR=~/.claude_personal_home claude auth login at login time, then a matching CLAUDE_CONFIG_DIR path on the provider instance in T3 Code Settings. T3 Code only offers Claude providers that share the same config directory for continuing an existing thread, since Claude Code keeps account and local state across multiple files under that directory. External/compatible setups (OpenRouter, Claude Code Router) are configured the same way: a dedicated CLAUDE_CONFIG_DIR plus provider-instance Environment variables (e.g. ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN marked sensitive).
• Codex (provider codex): a single account uses CODEX_HOME path: ~/.codex with an empty Shadow home path. Multiple accounts use one shared CODEX_HOME plus a second account's auth in a separate Shadow home path (e.g. ~/.codex_p), so both accounts can see the same T3/Codex sessions and either can continue an existing thread. A third Codex provider with a completely different CODEX_HOME path is instead treated as a separate workspace, not offered for existing threads.

Sensitive values placed in a provider's Environment variables (API keys, tokens) are stored as server secrets and are not sent back to the client app after saving.

Key Parameters

• Five built-in driver kinds: codex, claudeAgent, cursor, grok, opencode.
• Driver contract: driverKind, configSchema, create.
• Provider-facing commands: thread.turn.start, thread.turn.interrupt, thread.approval.respond, thread.user-input.respond, thread.checkpoint.revert, thread.session.stop, thread.runtime-mode.set, thread.interaction-mode.set.
• Buffered delivery threshold: MAX_BUFFERED_ASSISTANT_CHARS = 24,000 characters.
• Multi-account keys: Claude uses CLAUDE_CONFIG_DIR; Codex uses CODEX_HOME plus an optional Shadow home path.

When To Use

Consult this page when deciding which coding-agent CLI to run under T3 Code, when a provider shows as "not authenticated," when setting up more than one account for Claude or Codex, or when diagnosing why a thread does or does not offer a particular provider for continuation.

Risks & Pitfalls

• A provider CLI installed but not on the server's PATH (and without an explicit binary path configured) will not be detected.
• Cursor authentication is a common trap: installing Cursor CLI gives you cursor-agent, but you must run agent login, not cursor-agent login.
• Setting HOME instead of CLAUDE_CONFIG_DIR when logging in to a second Claude account writes credentials to the wrong location (~/.claude_personal_home/.claude instead of where T3 Code looks).
• Mixing up which Codex provider has the Shadow home path set, or copying ~/.codex wholesale into a shadow directory (rather than just auth.json), can make two providers appear to use the same account.
• Environment variable assignments belong in a provider's Environment variables section, not in Launch arguments.

Related Concepts

• t3code overview
• install and getting started
• permission modes
• provider claude code
• provider codex
• provider cursor
• provider grok build
• provider opencode

Sources

• raw/github_doc-docs-internals-providers-md.md
• raw/github_doc-docs-user-providers-claude-md.md
• raw/github_doc-docs-user-providers-codex-md.md
• raw/github_doc-readme-md.md