brains-cli 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brains-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "🧠 Brains.io — Install AI-powered dev agents. Build, review, architect, and ship with one command.",
   "main": "src/index.js",
   "bin": {
@@ -25,6 +25,7 @@
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
+    "openai": "^4.78.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "inquirer": "^8.2.6",

package/src/api.js

@@ -1,36 +1,28 @@
 'use strict';
 
-const Anthropic = require('@anthropic-ai/sdk');
-const { getApiKey, getModel } = require('./config');
-
-let client = null;
-
 /**
- * Initialize or return existing Anthropic client
+ * API Router — delegates to the active provider.
+ *
+ * All brain commands call streamMessage/sendMessage from here.
+ * This module resolves which provider to use and routes accordingly.
  */
-function getClient() {
-  if (client) return client;
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    throw new Error('NO_API_KEY');
-  }
-  client = new Anthropic({ apiKey });
-  return client;
-}
+
+const { getActiveProvider, getProviderApiKey, getProviderModel, getProviderBaseUrl } = require('./config');
+const { getProviderDef } = require('./providers/registry');
 
 /**
- * Stream a Claude response to the terminal in real-time.
+ * Stream a response from the active AI provider.
  * Returns the full assistant message text.
  *
  * @param {Object} opts
- * @param {string} opts.systemPrompt - System prompt
- * @param {Array} opts.messages - Conversation history [{role, content}]
- * @param {number} [opts.maxTokens] - Max tokens (default from config)
- * @param {string} [opts.model] - Model override
- * @param {Function} [opts.onText] - Callback for each text chunk
- * @param {Function} [opts.onStart] - Called when streaming starts
- * @param {Function} [opts.onEnd] - Called when streaming ends
- * @returns {Promise<string>} Full response text
+ * @param {string} opts.systemPrompt
+ * @param {Array}  opts.messages - [{role, content}]
+ * @param {number} [opts.maxTokens]
+ * @param {string} [opts.model] - Override model
+ * @param {Function} [opts.onText]
+ * @param {Function} [opts.onStart]
+ * @param {Function} [opts.onEnd]
+ * @returns {Promise<string>}
  */
 async function streamMessage(opts) {
   const {
@@ -43,34 +35,44 @@ async function streamMessage(opts) {
     onEnd = () => {},
   } = opts;
 
-  const anthropic = getClient();
-  const modelId = model || getModel();
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
 
-  let fullText = '';
+  if (!providerDef) {
+    throw new Error(`Unknown provider "${providerName}". Run: brains config set provider <name>`);
+  }
 
-  const stream = await anthropic.messages.stream({
-    model: modelId,
-    max_tokens: maxTokens,
-    system: systemPrompt,
-    messages: messages,
-  });
-
-  onStart();
-
-  for await (const event of stream) {
-    if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
-      const text = event.delta.text;
-      fullText += text;
-      onText(text);
-    }
+  const apiKey = getProviderApiKey(providerName);
+  const modelId = model || getProviderModel(providerName);
+  const baseURL = getProviderBaseUrl(providerName);
+
+  if (!apiKey && providerDef.requires_key !== false) {
+    throw new Error('NO_API_KEY');
   }
 
-  onEnd();
-  return fullText;
+  const callOpts = {
+    apiKey,
+    systemPrompt,
+    messages,
+    maxTokens,
+    model: modelId,
+    onText,
+    onStart,
+    onEnd,
+  };
+
+  if (providerDef.type === 'anthropic') {
+    const provider = require('./providers/anthropic');
+    return provider.streamMessage(callOpts);
+  } else {
+    const provider = require('./providers/openai-compat');
+    callOpts.baseURL = baseURL;
+    return provider.streamMessage(callOpts);
+  }
 }
 
 /**
- * Send a single message (non-streaming). Used for short tasks.
+ * Send a single message (non-streaming).
  */
 async function sendMessage(opts) {
   const {
@@ -80,24 +82,34 @@ async function sendMessage(opts) {
     model,
   } = opts;
 
-  const anthropic = getClient();
-  const modelId = model || getModel();
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
 
-  const response = await anthropic.messages.create({
-    model: modelId,
-    max_tokens: maxTokens,
-    system: systemPrompt,
-    messages: messages,
-  });
-
-  return response.content
-    .filter((block) => block.type === 'text')
-    .map((block) => block.text)
-    .join('');
+  if (!providerDef) {
+    throw new Error(`Unknown provider "${providerName}".`);
+  }
+
+  const apiKey = getProviderApiKey(providerName);
+  const modelId = model || getProviderModel(providerName);
+  const baseURL = getProviderBaseUrl(providerName);
+
+  if (!apiKey && providerDef.requires_key !== false) {
+    throw new Error('NO_API_KEY');
+  }
+
+  const callOpts = { apiKey, systemPrompt, messages, maxTokens, model: modelId };
+
+  if (providerDef.type === 'anthropic') {
+    const provider = require('./providers/anthropic');
+    return provider.sendMessage(callOpts);
+  } else {
+    const provider = require('./providers/openai-compat');
+    callOpts.baseURL = baseURL;
+    return provider.sendMessage(callOpts);
+  }
 }
 
 module.exports = {
-  getClient,
   streamMessage,
   sendMessage,
 };

package/src/commands/config.js

@@ -2,46 +2,101 @@
 
 const chalk = require('chalk');
 const Table = require('cli-table3');
-const { loadConfig, setConfigValue, getApiKey, maskApiKey, DEFAULTS } = require('../config');
-const { showSuccess, showError, showInfo, ACCENT, DIM } = require('../utils/ui');
+const {
+  loadConfig, saveConfig, setConfigValue,
+  getActiveProvider, getProviderApiKey, getProviderModel, getProviderBaseUrl,
+  setProviderApiKey, setProviderModel, setActiveProvider,
+  maskApiKey, DEFAULTS,
+} = require('../config');
+const { getAllProviders, getProviderDef, getAllProviderNames } = require('../providers/registry');
+const { showSuccess, showError, showInfo, showWarning, ACCENT, DIM, SUCCESS } = require('../utils/ui');
 
 async function configCommand(action, args) {
   if (!action) {
-    // Show all config
     showCurrentConfig();
     return;
   }
 
+  // ─── brains config set <key> <value> ───
   if (action === 'set') {
     if (args.length < 2) {
       showError('Usage: brains config set <key> <value>');
-      showInfo(`Example: ${ACCENT('brains config set api_key sk-ant-...')}`);
-      showInfo(`Example: ${ACCENT('brains config set model claude-sonnet-4-20250514')}`);
+      console.log('');
+      showInfo(`${ACCENT('provider')}     — Switch AI provider (groq, anthropic, gemini, openrouter, ollama)`);
+      showInfo(`${ACCENT('api_key')}      — Set API key for current provider`);
+      showInfo(`${ACCENT('model')}        — Set model for current provider`);
+      showInfo(`${ACCENT('max_tokens')}   — Set max tokens`);
+      console.log('');
+      showInfo(`Example: ${ACCENT('brains config set provider groq')}`);
+      showInfo(`Example: ${ACCENT('brains config set api_key gsk_...')}`);
       return;
     }
 
     const key = args[0];
     let value = args.slice(1).join(' ');
 
-    // Validate known keys
-    const validKeys = ['api_key', 'model', 'max_tokens', 'theme', 'telemetry'];
+    // ── Switch provider ──
+    if (key === 'provider') {
+      const providerDef = getProviderDef(value);
+      if (!providerDef) {
+        showError(`Unknown provider "${value}".`);
+        showInfo(`Available: ${getAllProviderNames().map(n => ACCENT(n)).join(', ')}`);
+        return;
+      }
+
+      setActiveProvider(value);
+      showSuccess(`Provider switched to ${chalk.bold(providerDef.name)}`);
+
+      // Check if key is configured
+      const apiKey = getProviderApiKey(value);
+      if (!apiKey && providerDef.requires_key !== false) {
+        console.log('');
+        showWarning(`No API key set for ${providerDef.name}.`);
+        showInfo(`Get one at: ${ACCENT(providerDef.key_url)}`);
+        showInfo(`Then run:   ${ACCENT(`brains config set api_key <your-key>`)}`);
+      } else {
+        showInfo(`Model: ${DIM(getProviderModel(value))}`);
+      }
+      console.log('');
+      return;
+    }
+
+    // ── Set API key (for current provider) ──
+    if (key === 'api_key') {
+      const currentProvider = getActiveProvider();
+      setProviderApiKey(currentProvider, value);
+      showSuccess(`API key saved for ${getProviderDef(currentProvider).name}: ${maskApiKey(value)}`);
+      console.log('');
+      return;
+    }
+
+    // ── Set model (for current provider) ──
+    if (key === 'model') {
+      const currentProvider = getActiveProvider();
+      setProviderModel(currentProvider, value);
+      showSuccess(`Model set for ${getProviderDef(currentProvider).name}: ${value}`);
+      console.log('');
+      return;
+    }
+
+    // ── Generic config keys ──
+    const validKeys = ['max_tokens', 'theme', 'telemetry'];
     if (!validKeys.includes(key)) {
       showError(`Unknown config key "${key}".`);
-      showInfo(`Valid keys: ${validKeys.map(k => ACCENT(k)).join(', ')}`);
+      showInfo(`Valid keys: provider, api_key, model, ${validKeys.map(k => ACCENT(k)).join(', ')}`);
       return;
     }
 
-    // Type coercion
     if (key === 'max_tokens') value = parseInt(value, 10);
     if (key === 'telemetry') value = value === 'true';
 
     setConfigValue(key, value);
-    const displayValue = key === 'api_key' ? maskApiKey(value) : value;
-    showSuccess(`${key} = ${displayValue}`);
+    showSuccess(`${key} = ${value}`);
     console.log('');
     return;
   }
 
+  // ─── brains config get <key> ───
   if (action === 'get') {
     if (args.length < 1) {
       showError('Usage: brains config get <key>');
@@ -49,13 +104,29 @@ async function configCommand(action, args) {
     }
 
     const key = args[0];
-    const config = loadConfig();
-    let value = config[key];
+
+    if (key === 'provider') {
+      const p = getActiveProvider();
+      const def = getProviderDef(p);
+      console.log(`\n  ${chalk.bold('provider')} = ${p} (${def ? def.name : 'unknown'})\n`);
+      return;
+    }
 
     if (key === 'api_key') {
-      value = maskApiKey(getApiKey());
+      const p = getActiveProvider();
+      const k = getProviderApiKey(p);
+      console.log(`\n  ${chalk.bold('api_key')} [${p}] = ${k ? maskApiKey(k) : chalk.red('(not set)')}\n`);
+      return;
     }
 
+    if (key === 'model') {
+      const p = getActiveProvider();
+      console.log(`\n  ${chalk.bold('model')} [${p}] = ${getProviderModel(p)}\n`);
+      return;
+    }
+
+    const config = loadConfig();
+    const value = config[key];
     if (value === undefined) {
       showInfo(`${key} is not set (default: ${DEFAULTS[key] || 'none'})`);
     } else {
@@ -64,20 +135,33 @@ async function configCommand(action, args) {
     return;
   }
 
+  // ─── brains config providers ───
+  if (action === 'providers') {
+    showProviderList();
+    return;
+  }
+
+  // ─── brains config reset ───
   if (action === 'reset') {
-    const { saveConfig } = require('../config');
-    saveConfig({ ...DEFAULTS });
-    showSuccess('Config reset to defaults.');
+    saveConfig({ ...DEFAULTS, providers: {} });
+    showSuccess('Config reset to defaults (provider: groq).');
     console.log('');
     return;
   }
 
-  showError(`Unknown action "${action}". Use: set, get, reset, or no action to view all.`);
+  showError(`Unknown action "${action}". Use: set, get, providers, reset, or no action to view all.`);
 }
 
+// ═══════════════════════════════════════════
+//  Display helpers
+// ═══════════════════════════════════════════
+
 function showCurrentConfig() {
   const config = loadConfig();
-  const apiKey = getApiKey();
+  const currentProvider = getActiveProvider();
+  const providerDef = getProviderDef(currentProvider);
+  const apiKey = getProviderApiKey(currentProvider);
+  const model = getProviderModel(currentProvider);
 
   console.log(`\n  ${chalk.bold('Brains Configuration')}\n`);
 
@@ -87,22 +171,66 @@ function showCurrentConfig() {
   });
 
   table.push(
-    [chalk.bold('api_key'), apiKey ? maskApiKey(apiKey) : chalk.red('(not set)')],
-    [chalk.bold('model'), config.model || DEFAULTS.model],
+    [chalk.bold('provider'), `${currentProvider} ${DIM(`(${providerDef ? providerDef.name : 'unknown'})`)}`],
+    [chalk.bold('api_key'), apiKey ? maskApiKey(apiKey) : (providerDef && providerDef.requires_key === false ? DIM('(not required)') : chalk.red('(not set)'))],
+    [chalk.bold('model'), model],
     [chalk.bold('max_tokens'), String(config.max_tokens || DEFAULTS.max_tokens)],
-    [chalk.bold('theme'), config.theme || DEFAULTS.theme],
     [chalk.bold('telemetry'), String(config.telemetry ?? DEFAULTS.telemetry)]
   );
 
   console.log(table.toString());
 
-  if (!apiKey) {
+  if (!apiKey && providerDef && providerDef.requires_key !== false) {
     console.log('');
-    showInfo(`Set your API key: ${ACCENT('brains config set api_key sk-ant-...')}`);
-    showInfo(`Or set env var: ${ACCENT('export ANTHROPIC_API_KEY=sk-ant-...')}`);
+    showInfo(`Set API key: ${ACCENT(`brains config set api_key <your-${currentProvider}-key>`)}`);
+    if (providerDef.key_url) {
+      showInfo(`Get one at:  ${ACCENT(providerDef.key_url)}`);
+    }
   }
 
   console.log('');
+  showInfo(`Switch provider: ${ACCENT('brains config set provider <name>')}`);
+  showInfo(`See all providers: ${ACCENT('brains config providers')}`);
+  console.log('');
+}
+
+function showProviderList() {
+  const currentProvider = getActiveProvider();
+  const allProviders = getAllProviders();
+
+  console.log(`\n  ${chalk.bold('Available Providers')}\n`);
+
+  const table = new Table({
+    head: [
+      chalk.white.bold('Provider'),
+      chalk.white.bold('Type'),
+      chalk.white.bold('Default Model'),
+      chalk.white.bold('Free?'),
+      chalk.white.bold('Status'),
+    ],
+    style: { head: [], border: ['dim'] },
+    colWidths: [16, 12, 36, 8, 14],
+  });
+
+  for (const [name, def] of Object.entries(allProviders)) {
+    const isActive = name === currentProvider;
+    const hasKey = !!getProviderApiKey(name) || def.requires_key === false;
+
+    table.push([
+      isActive ? chalk.hex('#7B2FFF').bold(`▸ ${name}`) : `  ${name}`,
+      DIM(def.type),
+      DIM(def.default_model),
+      def.free ? SUCCESS('Yes') : DIM('Paid'),
+      hasKey ? SUCCESS('Ready') : chalk.yellow('Need key'),
+    ]);
+  }
+
+  console.log(table.toString());
+
+  console.log('');
+  showInfo(`Active: ${ACCENT(currentProvider)}`);
+  showInfo(`Switch: ${ACCENT('brains config set provider <name>')}`);
+  console.log('');
 }
 
 module.exports = { config: configCommand };

package/src/commands/run.js

@@ -7,7 +7,12 @@ const path = require('path');
 const fs = require('fs');
 const readline = require('readline');
 const { getBrainById } = require('../registry');
-const { getApiKey, getModel, saveSession, setConfigValue } = require('../config');
+const {
+  getActiveProvider, getProviderApiKey, getProviderModel,
+  setProviderApiKey, setActiveProvider,
+  getModel, saveSession,
+} = require('../config');
+const { getProviderDef, getAllProviderNames } = require('../providers/registry');
 const { streamMessage } = require('../api');
 const { readFilesForReview, parseFileBlocks, writeFileBlocks, generateTreeView } = require('../utils/files');
 const { showSuccess, showError, showInfo, showWarning, ACCENT, DIM, SUCCESS, WARN } = require('../utils/ui');
@@ -33,23 +38,45 @@ function loadBrainConfig(brainId) {
 }
 
 /**
- * Ensure API key is available. Prompt user if missing.
+ * Ensure API key is available for the active provider.
+ * Prompts user if missing. Offers provider switching if no key.
  */
 async function ensureApiKey() {
-  let key = getApiKey();
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
+
+  // Ollama doesn't need a key
+  if (providerDef && providerDef.requires_key === false) {
+    return 'not-required';
+  }
+
+  let key = getProviderApiKey(providerName);
   if (key) return key;
 
   console.log('');
-  showWarning('No Anthropic API key found.');
-  showInfo(`Get one at ${ACCENT('https://console.anthropic.com/')}\n`);
+  showWarning(`No API key found for ${chalk.bold(providerDef ? providerDef.name : providerName)}.`);
+
+  if (providerDef && providerDef.key_url) {
+    showInfo(`Get one at ${ACCENT(providerDef.key_url)}\n`);
+  }
+
+  const keyHint = providerDef && providerDef.key_prefix
+    ? `Key should start with ${providerDef.key_prefix}`
+    : '';
 
   const { apiKey } = await inquirer.prompt([
     {
       type: 'password',
       name: 'apiKey',
-      message: 'Enter your Anthropic API key:',
+      message: `Enter your ${providerDef ? providerDef.name : providerName} API key:`,
       mask: '*',
-      validate: (v) => v.startsWith('sk-ant-') ? true : 'Key should start with sk-ant-',
+      validate: (v) => {
+        if (!v || v.length < 5) return 'Please enter a valid API key';
+        if (providerDef && providerDef.key_prefix && !v.startsWith(providerDef.key_prefix)) {
+          return keyHint;
+        }
+        return true;
+      },
     },
   ]);
 
@@ -63,12 +90,15 @@ async function ensureApiKey() {
   ]);
 
   if (save) {
-    setConfigValue('api_key', apiKey);
+    setProviderApiKey(providerName, apiKey);
     showSuccess('API key saved.');
   }
 
   // Set in environment for this session
-  process.env.ANTHROPIC_API_KEY = apiKey;
+  if (providerDef && providerDef.key_env) {
+    process.env[providerDef.key_env] = apiKey;
+  }
+
   return apiKey;
 }
 
@@ -126,8 +156,12 @@ function showSessionHeader(brain, stackedBrains) {
       chalk.hex(color).bold('  │  ') + DIM(`+ ${stackedBrains.map((b) => b.name).join(', ')}`)
     );
   }
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
+  const providerLabel = providerDef ? providerDef.name : providerName;
+
   console.log(chalk.hex(color).bold('  │  ') + DIM(`Stack: ${brain.stack.join(', ')}`));
-  console.log(chalk.hex(color).bold('  │  ') + DIM(`Model: ${getModel()}`));
+  console.log(chalk.hex(color).bold('  │  ') + DIM(`Provider: ${providerLabel}  •  Model: ${getModel()}`));
   console.log(chalk.hex(color).bold('  └─────────────────────────────────────────────────────'));
   console.log('');
 }
@@ -553,15 +587,24 @@ async function runConversationalBrain(brain, config, stackedBrains, options) {
 function handleApiError(err) {
   console.log('');
 
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
+  const providerLabel = providerDef ? providerDef.name : providerName;
+
   if (err.message === 'NO_API_KEY') {
-    showError('No API key configured.');
-    showInfo(`Run ${ACCENT('brains config set api_key <your-key>')} or set ANTHROPIC_API_KEY env var.`);
+    showError(`No API key configured for ${providerLabel}.`);
+    showInfo(`Run ${ACCENT('brains config set api_key <your-key>')}`);
+    if (providerDef && providerDef.key_env) {
+      showInfo(`Or set env var: ${ACCENT(`export ${providerDef.key_env}=<your-key>`)}`);
+    }
     return;
   }
 
-  if (err.status === 401) {
-    showError('Invalid API key.');
-    showInfo(`Check your key at ${ACCENT('https://console.anthropic.com/')}`);
+  if (err.status === 401 || err.code === 'invalid_api_key') {
+    showError(`Invalid API key for ${providerLabel}.`);
+    if (providerDef && providerDef.key_url) {
+      showInfo(`Check your key at ${ACCENT(providerDef.key_url)}`);
+    }
     showInfo(`Update with: ${ACCENT('brains config set api_key <your-key>')}`);
     return;
   }
@@ -569,18 +612,26 @@ function handleApiError(err) {
   if (err.status === 429) {
     showError('Rate limit exceeded.');
     showInfo('Wait a moment and try again, or check your API usage limits.');
+    if (providerDef && providerDef.free) {
+      showInfo(`${providerLabel} free tier has rate limits. Consider upgrading or switching providers.`);
+      showInfo(`Switch: ${ACCENT('brains config set provider <name>')}`);
+    }
     return;
   }
 
   if (err.status === 529 || err.status === 503) {
-    showError('Claude API is temporarily overloaded.');
+    showError(`${providerLabel} is temporarily overloaded.`);
     showInfo('Try again in a few seconds.');
     return;
   }
 
   if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT') {
-    showError('Network error — cannot reach the Claude API.');
-    showInfo('Check your internet connection and try again.');
+    showError(`Network error — cannot reach ${providerLabel}.`);
+    if (providerName === 'ollama') {
+      showInfo('Is Ollama running? Start it with: ollama serve');
+    } else {
+      showInfo('Check your internet connection and try again.');
+    }
     return;
   }
 
@@ -589,6 +640,7 @@ function handleApiError(err) {
   if (err.status) {
     showInfo(`Status: ${err.status}`);
   }
+  showInfo(`Provider: ${providerLabel} | Model: ${getModel()}`);
   console.log('');
 }
 

package/src/config.js

@@ -3,13 +3,14 @@
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const { getProviderDef } = require('./providers/registry');
 
 const BRAINS_DIR = path.join(os.homedir(), '.brains');
 const CONFIG_FILE = path.join(BRAINS_DIR, 'config.json');
 const SESSIONS_DIR = path.join(BRAINS_DIR, 'sessions');
 
 const DEFAULTS = {
-  model: 'claude-sonnet-4-20250514',
+  provider: 'groq',
   max_tokens: 8096,
   theme: 'dark',
   telemetry: false,
@@ -28,12 +29,50 @@ function loadConfig() {
   ensureDirs();
   try {
     if (fs.existsSync(CONFIG_FILE)) {
-      return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8')) };
+      const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+      return migrateConfig(raw);
     }
   } catch (e) {
     // corrupted config, reset
   }
-  return { ...DEFAULTS };
+  return { ...DEFAULTS, providers: {} };
+}
+
+/**
+ * Migrate old config format (flat api_key/model) to new provider-based format.
+ */
+function migrateConfig(raw) {
+  const config = { ...DEFAULTS, ...raw };
+
+  // Ensure providers object exists
+  if (!config.providers) {
+    config.providers = {};
+  }
+
+  // Migrate old flat api_key → providers.anthropic.api_key
+  if (config.api_key && !config.providers.anthropic) {
+    config.providers.anthropic = {
+      api_key: config.api_key,
+      model: config.model || 'claude-sonnet-4-20250514',
+    };
+    delete config.api_key;
+  }
+
+  // Migrate old flat model if it was an anthropic model
+  if (config.model && config.model.startsWith('claude-')) {
+    if (!config.providers.anthropic) config.providers.anthropic = {};
+    config.providers.anthropic.model = config.model;
+    delete config.model;
+  } else if (config.model) {
+    delete config.model;
+  }
+
+  // If no provider is set, default to groq
+  if (!config.provider) {
+    config.provider = DEFAULTS.provider;
+  }
+
+  return config;
 }
 
 function saveConfig(config) {
@@ -52,23 +91,109 @@ function setConfigValue(key, value) {
   saveConfig(config);
 }
 
+// ═══════════════════════════════════════════
+//  PROVIDER-AWARE GETTERS
+// ═══════════════════════════════════════════
+
 /**
- * Resolve API key from: env var > config file > null
+ * Get the currently active provider name.
  */
-function getApiKey() {
-  if (process.env.ANTHROPIC_API_KEY) {
-    return process.env.ANTHROPIC_API_KEY;
+function getActiveProvider() {
+  const config = loadConfig();
+  return config.provider || DEFAULTS.provider;
+}
+
+/**
+ * Resolve API key for a provider: env var > config > null
+ */
+function getProviderApiKey(providerName) {
+  const providerDef = getProviderDef(providerName);
+
+  // 1. Check environment variable
+  if (providerDef && providerDef.key_env && process.env[providerDef.key_env]) {
+    return process.env[providerDef.key_env];
   }
+
+  // 2. Check config file
   const config = loadConfig();
-  if (config.api_key) {
-    return config.api_key;
+  const providerConfig = config.providers && config.providers[providerName];
+  if (providerConfig && providerConfig.api_key) {
+    return providerConfig.api_key;
   }
+
   return null;
 }
 
-function getModel() {
+/**
+ * Get the model for a provider: config > default
+ */
+function getProviderModel(providerName) {
+  const config = loadConfig();
+  const providerConfig = config.providers && config.providers[providerName];
+  if (providerConfig && providerConfig.model) {
+    return providerConfig.model;
+  }
+
+  // Fallback to provider's default model
+  const providerDef = getProviderDef(providerName);
+  return providerDef ? providerDef.default_model : 'unknown';
+}
+
+/**
+ * Get the base URL for a provider: config override > provider default
+ */
+function getProviderBaseUrl(providerName) {
+  const config = loadConfig();
+  const providerConfig = config.providers && config.providers[providerName];
+  if (providerConfig && providerConfig.base_url) {
+    return providerConfig.base_url;
+  }
+
+  const providerDef = getProviderDef(providerName);
+  return providerDef ? providerDef.base_url : null;
+}
+
+/**
+ * Save API key for a specific provider.
+ */
+function setProviderApiKey(providerName, apiKey) {
+  const config = loadConfig();
+  if (!config.providers) config.providers = {};
+  if (!config.providers[providerName]) config.providers[providerName] = {};
+  config.providers[providerName].api_key = apiKey;
+  saveConfig(config);
+}
+
+/**
+ * Save model for a specific provider.
+ */
+function setProviderModel(providerName, model) {
+  const config = loadConfig();
+  if (!config.providers) config.providers = {};
+  if (!config.providers[providerName]) config.providers[providerName] = {};
+  config.providers[providerName].model = model;
+  saveConfig(config);
+}
+
+/**
+ * Switch the active provider.
+ */
+function setActiveProvider(providerName) {
   const config = loadConfig();
-  return config.model || DEFAULTS.model;
+  config.provider = providerName;
+  saveConfig(config);
+}
+
+// ═══════════════════════════════════════════
+//  BACKWARD-COMPAT GETTERS (used by run.js session header)
+// ═══════════════════════════════════════════
+
+function getModel() {
+  return getProviderModel(getActiveProvider());
+}
+
+function getApiKey() {
+  return getProviderApiKey(getActiveProvider());
 }
 
 function maskApiKey(key) {
@@ -97,6 +222,13 @@ module.exports = {
   saveConfig,
   getConfigValue,
   setConfigValue,
+  getActiveProvider,
+  getProviderApiKey,
+  getProviderModel,
+  getProviderBaseUrl,
+  setProviderApiKey,
+  setProviderModel,
+  setActiveProvider,
   getApiKey,
   getModel,
   maskApiKey,

package/src/providers/anthropic.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const Anthropic = require('@anthropic-ai/sdk');
+
+let client = null;
+let cachedKey = null;
+
+function getClient(apiKey) {
+  // Re-create if key changed
+  if (client && cachedKey === apiKey) return client;
+  client = new Anthropic({ apiKey });
+  cachedKey = apiKey;
+  return client;
+}
+
+/**
+ * Stream a message using Anthropic's native API.
+ * System prompt is a separate parameter (not a message).
+ */
+async function streamMessage(opts) {
+  const {
+    apiKey,
+    systemPrompt,
+    messages,
+    maxTokens,
+    model,
+    onText,
+    onStart,
+    onEnd,
+  } = opts;
+
+  const anthropic = getClient(apiKey);
+  let fullText = '';
+
+  const stream = await anthropic.messages.stream({
+    model,
+    max_tokens: maxTokens,
+    system: systemPrompt,
+    messages,
+  });
+
+  onStart();
+
+  for await (const event of stream) {
+    if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+      const text = event.delta.text;
+      fullText += text;
+      onText(text);
+    }
+  }
+
+  onEnd();
+  return fullText;
+}
+
+/**
+ * Send a single message (non-streaming).
+ */
+async function sendMessage(opts) {
+  const {
+    apiKey,
+    systemPrompt,
+    messages,
+    maxTokens,
+    model,
+  } = opts;
+
+  const anthropic = getClient(apiKey);
+
+  const response = await anthropic.messages.create({
+    model,
+    max_tokens: maxTokens,
+    system: systemPrompt,
+    messages,
+  });
+
+  return response.content
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+}
+
+module.exports = { streamMessage, sendMessage };

package/src/providers/openai-compat.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const OpenAI = require('openai');
+
+const clients = {};
+
+function getClient(baseURL, apiKey) {
+  const cacheKey = baseURL + '::' + (apiKey || 'nokey');
+  if (clients[cacheKey]) return clients[cacheKey];
+
+  clients[cacheKey] = new OpenAI({
+    apiKey: apiKey || 'ollama',  // Ollama doesn't need a key but SDK requires one
+    baseURL,
+  });
+
+  return clients[cacheKey];
+}
+
+/**
+ * Stream a message using OpenAI-compatible API (Groq, Gemini, OpenRouter, Ollama).
+ * System prompt becomes a system message.
+ */
+async function streamMessage(opts) {
+  const {
+    apiKey,
+    baseURL,
+    systemPrompt,
+    messages,
+    maxTokens,
+    model,
+    onText,
+    onStart,
+    onEnd,
+  } = opts;
+
+  const openai = getClient(baseURL, apiKey);
+
+  // Convert Anthropic-style (separate system) to OpenAI-style (system message)
+  const fullMessages = [
+    { role: 'system', content: systemPrompt },
+    ...messages,
+  ];
+
+  let fullText = '';
+
+  const stream = await openai.chat.completions.create({
+    model,
+    max_tokens: maxTokens,
+    messages: fullMessages,
+    stream: true,
+  });
+
+  onStart();
+
+  for await (const chunk of stream) {
+    const text = chunk.choices[0]?.delta?.content;
+    if (text) {
+      fullText += text;
+      onText(text);
+    }
+  }
+
+  onEnd();
+  return fullText;
+}
+
+/**
+ * Send a single message (non-streaming).
+ */
+async function sendMessage(opts) {
+  const {
+    apiKey,
+    baseURL,
+    systemPrompt,
+    messages,
+    maxTokens,
+    model,
+  } = opts;
+
+  const openai = getClient(baseURL, apiKey);
+
+  const fullMessages = [
+    { role: 'system', content: systemPrompt },
+    ...messages,
+  ];
+
+  const response = await openai.chat.completions.create({
+    model,
+    max_tokens: maxTokens,
+    messages: fullMessages,
+  });
+
+  return response.choices[0]?.message?.content || '';
+}
+
+module.exports = { streamMessage, sendMessage };

package/src/providers/registry.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Provider Registry — defines all supported AI providers.
+ *
+ * Each provider has:
+ *   type        — 'anthropic' or 'openai' (OpenAI-compatible API)
+ *   name        — Display name
+ *   base_url    — API endpoint (for openai-type providers)
+ *   default_model — Fallback model
+ *   models      — Available models
+ *   key_prefix  — Expected API key prefix (for validation hint)
+ *   key_env     — Environment variable to check for API key
+ *   key_url     — Where to get an API key
+ *   requires_key — false for providers that don't need a key (Ollama)
+ *   free        — true if provider has a free tier
+ */
+const PROVIDERS = {
+  groq: {
+    name: 'Groq',
+    type: 'openai',
+    base_url: 'https://api.groq.com/openai/v1',
+    default_model: 'llama-3.3-70b-versatile',
+    models: [
+      'llama-3.3-70b-versatile',
+      'llama-3.1-8b-instant',
+      'mixtral-8x7b-32768',
+      'gemma2-9b-it',
+    ],
+    key_prefix: 'gsk_',
+    key_env: 'GROQ_API_KEY',
+    key_url: 'https://console.groq.com/',
+    requires_key: true,
+    free: true,
+  },
+
+  anthropic: {
+    name: 'Anthropic (Claude)',
+    type: 'anthropic',
+    base_url: null,
+    default_model: 'claude-sonnet-4-20250514',
+    models: [
+      'claude-sonnet-4-20250514',
+      'claude-haiku-4-20250514',
+    ],
+    key_prefix: 'sk-ant-',
+    key_env: 'ANTHROPIC_API_KEY',
+    key_url: 'https://console.anthropic.com/',
+    requires_key: true,
+    free: false,
+  },
+
+  gemini: {
+    name: 'Google Gemini',
+    type: 'openai',
+    base_url: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+    default_model: 'gemini-2.0-flash',
+    models: [
+      'gemini-2.0-flash',
+      'gemini-1.5-flash',
+      'gemini-1.5-pro',
+    ],
+    key_prefix: '',
+    key_env: 'GEMINI_API_KEY',
+    key_url: 'https://aistudio.google.com/',
+    requires_key: true,
+    free: true,
+  },
+
+  openrouter: {
+    name: 'OpenRouter',
+    type: 'openai',
+    base_url: 'https://openrouter.ai/api/v1',
+    default_model: 'meta-llama/llama-3.3-70b-instruct:free',
+    models: [
+      'meta-llama/llama-3.3-70b-instruct:free',
+      'mistralai/mistral-7b-instruct:free',
+      'google/gemma-2-9b-it:free',
+    ],
+    key_prefix: 'sk-or-',
+    key_env: 'OPENROUTER_API_KEY',
+    key_url: 'https://openrouter.ai/',
+    requires_key: true,
+    free: true,
+  },
+
+  ollama: {
+    name: 'Ollama (Local)',
+    type: 'openai',
+    base_url: 'http://localhost:11434/v1',
+    default_model: 'llama3',
+    models: [
+      'llama3',
+      'llama3.1',
+      'codellama',
+      'mistral',
+      'mixtral',
+      'phi3',
+    ],
+    key_prefix: '',
+    key_env: '',
+    key_url: 'https://ollama.com/',
+    requires_key: false,
+    free: true,
+  },
+};
+
+function getProviderDef(name) {
+  return PROVIDERS[name] || null;
+}
+
+function getAllProviderNames() {
+  return Object.keys(PROVIDERS);
+}
+
+function getAllProviders() {
+  return PROVIDERS;
+}
+
+module.exports = {
+  PROVIDERS,
+  getProviderDef,
+  getAllProviderNames,
+  getAllProviders,
+};