# LLM Provider

Adds a new LLM provider implementing LLMProvider interface with call() and stream()...

- Repository: https://github.com/caliber-ai-org/ai-setup (1310 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-09-24
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add caliber-ai-org/ai-setup --skill llm-provider -g -a claude-code -y`
Codex: `npx skills add caliber-ai-org/ai-setup --skill llm-provider -g -a codex -y`
Cursor: `npx skills add caliber-ai-org/ai-setup --skill llm-provider -g -a cursor -y`
Gemini CLI: `npx skills add caliber-ai-org/ai-setup --skill llm-provider -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add caliber-ai-org/ai-setup`

## Description

Adds a new LLM provider implementing LLMProvider interface with call() and stream() methods. Integrates with provider factory in src/llm/index.ts, config detection in src/llm/config.ts, and error handling via tracking and recovery. Use when adding a new model backend, integrating a third-party LLM API, or extending LLM platform support. Do NOT use for fixing bugs in existing providers, modifying existing provider behavior, or changing the LLMProvider interface.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# LLM Provider

## Critical

1. **All providers MUST implement the LLMProvider interface** from src/llm/types.ts with three methods:
   - call(options: LLMCallOptions): Promise<string>, single non-streaming call returning text
   - stream(options: LLMStreamOptions, callbacks: LLMStreamCallbacks): Promise<void>, streaming call invoking callbacks
   - listModels?(): Promise<string[]>, optional; list available models from the API

2. **Initialize client in constructor and store defaultModel from config**. Example: `this.client = new YourSDK({ apiKey: config.apiKey })`. Never lazy-initialize on first call, providers are instantiated once and cached in src/llm/index.ts.

3. **For EVERY response in call() and stream(), invoke trackUsage(model, usage)** from src/llm/usage.js before returning/ending. This is mandatory, it captures token metrics for CLI telemetry and cost analysis. If the API doesn't return usage data, estimate via estimateTokens(text), which assumes ~4 chars per token.

4. **Both call() and stream() must respect the model parameter** using pattern: `options.model || this.defaultModel`. Never hardcode model names. Callers supply model overrides via LLMCallOptions.model.

5. **Error handling: catch all errors, preserve error messages unchanged**. The retry logic in src/llm/index.ts handles transient errors (ECONNRESET, socket hang up, 529 overload). For seat-based providers (Cursor, Claude CLI), wrap stderr via parseSeatBasedError() for user-friendly messages.

6. **Always update ProviderType union** (Step 2), DEFAULT_MODELS (Step 4), and createProvider() switch case (Step 5) in lock-step. Missing any one breaks the build or causes runtime Unknown provider error.

## Instructions

### Step 1: Create provider class file
Verify directory exists: `ls -la src/llm/`. Create `src/llm/your-provider.ts`. Match existing provider patterns (src/llm/anthropic.ts, src/llm/openai-compat.ts).

The rest: https://github.com/caliber-ai-org/ai-setup/blob/HEAD/.agents/skills/llm-provider/SKILL.md