Providers

Providers translate Clanker's internal run contract to a concrete execution backend. Built-in adapters are local, codex, and claude.

Local

The local provider runs registered TypeScript handlers in process. It supports deterministic offline tests, examples, streaming deltas, approvals, and cancellation without model credentials.

Codex

The Codex adapter uses @openai/codex-sdk and the machine's existing Codex authentication. It maps model, sandbox, approval-policy, reasoning-effort, workspace, attachments, and MCP configuration; provider events become normalized Clanker events.

Codex approvals remain provider-native because its SDK exposes no interactive approval callback. Declared Clanker runtime tools are bridged into the run over a loopback-only MCP server.

Claude

The Claude adapter uses @anthropic-ai/claude-agent-sdk and the machine's existing Claude Code authentication. It maps models, tools, permission modes, MCP servers, structured output, and streamed messages.

Claude's canUseTool callback is bridged to Clanker's approval handler. With no handler, approval-gated tools are denied by default. File and shell agents should set presetSystemPrompt: true so Claude Code supplies its working-directory and platform context.

Portable definitions

definePortableAgent leaves the provider unbound. bindProvider supplies a provider per project or host while preserving the same instructions, schemas, requirements, and catalog identity.

Use buildProviderSupportMatrix() when behavior depends on capabilities. It distinguishes native, mapped, runtime-owned, runtime-bridged, and unsupported features instead of implying that every backend behaves identically.