@plexor-dev/claude-code-plugin-staging 0.1.0-beta.18 → 0.1.0-beta.19

package/commands/plexor-enabled.js

@@ -240,7 +240,7 @@ function main() {
     console.log(`│  ✗ Cannot Enable Plexor                     │`);
     console.log(`├─────────────────────────────────────────────┤`);
     console.log(`│  No API key configured.                     │`);
-    console.log(`│  Run /plexor-login <api-key> first.         │`);
+    console.log(`│  Run /plexor-setup first.                   │`);
     console.log(`├─────────────────────────────────────────────┤`);
     console.log(`│  Get your API key at:                       │`);
     console.log(`│  https://plexor.dev/dashboard/api-keys      │`);
@@ -256,7 +256,7 @@ function main() {
     console.log(`│  Invalid API key format in config.          │`);
     console.log(`│  Keys must start with "plx_" (20+ chars).   │`);
     console.log(`├─────────────────────────────────────────────┤`);
-    console.log(`│  Run /plexor-login <api-key> to fix.        │`);
+    console.log(`│  Run /plexor-setup to fix it.               │`);
     console.log(`└─────────────────────────────────────────────┘`);
     process.exit(1);
   }

package/commands/plexor-setup.md

@@ -45,7 +45,7 @@ Options:
 
 **Step 3A: Claude MAX User Setup**
 
-If user selected "Yes, I have Claude MAX":
+If user selected the "Claude MAX subscription (Pro/Team/Enterprise)" option:
 
 1. Ask for their Plexor API key:
    "Please provide your Plexor API key (starts with 'plx_')."
@@ -75,11 +75,12 @@ If user selected "Yes, I have Claude MAX":
 {
   "env": {
     "ANTHROPIC_BASE_URL": "https://staging.api.plexor.dev/gateway/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]"
+    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]",
+    "ANTHROPIC_API_KEY": "[user's Plexor key]"
   }
 }
 ```
-Note: Preserve any existing settings, just add/update the env block.
+Note: Preserve unrelated settings, but replace `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_API_KEY` in the env block. This is required when the user previously configured Claude with direct API auth.
 
 4. Show the user:
 ```
@@ -107,7 +108,7 @@ Changes take effect immediately in all Claude Code sessions!
 
 **Step 3B: API Key User Setup**
 
-If user selected "No, I'll use a Plexor API key":
+If user selected the "Pay-per-use via Plexor" option:
 
 1. Ask for their Plexor API key:
    "Please provide your Plexor API key (starts with 'plx_')."
@@ -137,11 +138,12 @@ If user selected "No, I'll use a Plexor API key":
 {
   "env": {
     "ANTHROPIC_BASE_URL": "https://staging.api.plexor.dev/gateway/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]"
+    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]",
+    "ANTHROPIC_API_KEY": "[user's Plexor key]"
   }
 }
 ```
-Note: Preserve any existing settings, just add/update the env block.
+Note: Preserve unrelated settings, but replace `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_API_KEY` in the env block. This is required when the user previously configured Claude with direct API auth.
 
 4. Show the user:
 ```
@@ -169,7 +171,7 @@ Changes take effect immediately in all Claude Code sessions!
 
 **NOTES**:
 - The `~/.claude/settings.json` env block is the KEY mechanism that routes Claude Code through Plexor
-- ANTHROPIC_AUTH_TOKEN takes precedence over ANTHROPIC_API_KEY (use AUTH_TOKEN for the Plexor key)
+- Set both `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` to the Plexor key so Claude cannot bypass the Plexor gateway with a previously saved direct API key
 - Changes take effect immediately - no shell restart needed
 
 After completing all steps, STOP. DO NOT restart the workflow. DO NOT re-execute any commands.

package/commands/plexor-status.js

@@ -13,6 +13,26 @@ const https = require('https');
 const { HOME_DIR, CONFIG_PATH, SESSION_PATH, SESSION_TIMEOUT_MS } = require('../lib/constants');
 const CLAUDE_SETTINGS_PATH = path.join(HOME_DIR, '.claude', 'settings.json');
 
+function isManagedGatewayUrl(baseUrl = '') {
+  return (
+    baseUrl.includes('plexor') ||
+    baseUrl.includes('staging.api') ||
+    baseUrl.includes('ngrok') ||
+    baseUrl.includes('localtunnel') ||
+    baseUrl.includes('localhost') ||
+    baseUrl.includes('127.0.0.1')
+  );
+}
+
+function getPlexorAuthKey(env = {}) {
+  const apiKey = env.ANTHROPIC_API_KEY || '';
+  const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (apiKey.startsWith('plx_')) return apiKey;
+  if (authToken.startsWith('plx_')) return authToken;
+  return apiKey || authToken || '';
+}
+
 /**
  * Check if Claude Code is actually routing through Plexor
  * by reading ~/.claude/settings.json
@@ -22,10 +42,10 @@ function getRoutingStatus() {
     const data = fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf8');
     const settings = JSON.parse(data);
     const baseUrl = settings.env?.ANTHROPIC_BASE_URL || '';
-    const hasToken = !!settings.env?.ANTHROPIC_AUTH_TOKEN;
-    const isPlexorRouting = baseUrl.includes('plexor') || baseUrl.includes('staging.api');
+    const authKey = getPlexorAuthKey(settings.env);
+    const isPlexorRouting = isManagedGatewayUrl(baseUrl);
     return {
-      active: isPlexorRouting && hasToken,
+      active: isPlexorRouting && !!authKey,
       baseUrl,
       isStaging: baseUrl.includes('staging')
     };
@@ -44,14 +64,14 @@ function detectPartialState() {
     const data = fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf8');
     const settings = JSON.parse(data);
     const baseUrl = settings.env?.ANTHROPIC_BASE_URL || '';
-    const authToken = settings.env?.ANTHROPIC_AUTH_TOKEN || '';
-    const isPlexorUrl = baseUrl.includes('plexor') || baseUrl.includes('staging.api');
+    const authKey = getPlexorAuthKey(settings.env);
+    const isPlexorUrl = isManagedGatewayUrl(baseUrl);
 
-    if (isPlexorUrl && !authToken) {
-      return { partial: true, issue: 'Plexor URL set but no auth token' };
+    if (isPlexorUrl && !authKey) {
+      return { partial: true, issue: 'Plexor URL set but no Plexor auth key' };
     }
-    if (isPlexorUrl && !authToken.startsWith('plx_')) {
-      return { partial: true, issue: 'Plexor URL set but auth token is not a Plexor key' };
+    if (isPlexorUrl && !authKey.startsWith('plx_')) {
+      return { partial: true, issue: 'Plexor URL set but auth key is not a Plexor key' };
     }
     return { partial: false, issue: null };
   } catch {
@@ -102,7 +122,7 @@ function loadConfig() {
     return config;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      console.log('Config file is corrupted. Run /plexor-login to reconfigure.');
+      console.log('Config file is corrupted. Run /plexor-setup to reconfigure.');
     }
     return null;
   }
@@ -154,7 +174,7 @@ async function main() {
   // Read config with integrity checking
   const config = loadConfig();
   if (!config) {
-    console.log('Not configured. Run /plexor-login first.');
+    console.log('Not configured. Run /plexor-setup.');
     process.exit(1);
   }
 
@@ -166,14 +186,14 @@ async function main() {
   const apiUrl = config.settings?.apiUrl || 'https://api.plexor.dev';
 
   if (!apiKey) {
-    console.log('Not authenticated. Run /plexor-login first.');
+    console.log('Not authenticated. Run /plexor-setup.');
     process.exit(1);
   }
 
   // Validate API key format
   if (!isValidApiKeyFormat(apiKey)) {
     console.log('Invalid API key format. Keys must start with "plx_" and be at least 20 characters.');
-    console.log('Run /plexor-login with a valid API key.');
+    console.log('Run /plexor-setup with a valid Plexor API key.');
     process.exit(1);
   }
 
@@ -278,7 +298,7 @@ ${line(`└── Cost saved: $${sessionCostSaved}`)}
   const partialState = detectPartialState();
   if (partialState.partial) {
     console.log(`  ⚠ PARTIAL STATE DETECTED: ${partialState.issue}`);
-    console.log(`    Run /plexor-login to fix, or /plexor-logout to disable routing\n`);
+    console.log(`    Run /plexor-setup to repair, or /plexor-logout to disable routing\n`);
   }
 
   // Check for state mismatch between config enabled flag and routing status

package/commands/plexor-uninstall.js

@@ -99,17 +99,43 @@ function disableRoutingManually() {
       return { success: true, message: 'No env block in settings' };
     }
 
-    // Check if Plexor routing is active
-    const baseUrl = settings.env.ANTHROPIC_BASE_URL || '';
-    const isPlexorRouting = baseUrl.includes('plexor') || baseUrl.includes('staging.api');
-
-    if (!isPlexorRouting) {
+    const isManagedGatewayUrl = (baseUrl = '') =>
+      baseUrl.includes('plexor') ||
+      baseUrl.includes('staging.api') ||
+      baseUrl.includes('localhost') ||
+      baseUrl.includes('127.0.0.1') ||
+      baseUrl.includes('ngrok') ||
+      baseUrl.includes('localtunnel');
+    const isPlexorApiKey = (value = '') =>
+      typeof value === 'string' && value.startsWith('plx_');
+
+    const hasManagedBaseUrl = isManagedGatewayUrl(settings.env.ANTHROPIC_BASE_URL || '');
+    const hasPlexorAuthToken = isPlexorApiKey(settings.env.ANTHROPIC_AUTH_TOKEN || '');
+    const hasPlexorApiKey = isPlexorApiKey(settings.env.ANTHROPIC_API_KEY || '');
+
+    if (!hasManagedBaseUrl && !hasPlexorAuthToken && !hasPlexorApiKey) {
       return { success: true, message: 'Plexor routing not active' };
     }
 
-    // Remove Plexor env vars
-    delete settings.env.ANTHROPIC_BASE_URL;
-    delete settings.env.ANTHROPIC_AUTH_TOKEN;
+    if (hasManagedBaseUrl) {
+      delete settings.env.ANTHROPIC_BASE_URL;
+    }
+    if (hasPlexorAuthToken) {
+      delete settings.env.ANTHROPIC_AUTH_TOKEN;
+    }
+    if (hasPlexorApiKey) {
+      delete settings.env.ANTHROPIC_API_KEY;
+    }
+
+    if (!settings.env.ANTHROPIC_API_KEY && settings.env.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY) {
+      settings.env.ANTHROPIC_API_KEY = settings.env.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY;
+    }
+    if (!settings.env.ANTHROPIC_AUTH_TOKEN && settings.env.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN) {
+      settings.env.ANTHROPIC_AUTH_TOKEN = settings.env.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN;
+    }
+
+    delete settings.env.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY;
+    delete settings.env.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN;
 
     // Clean up empty env block
     if (Object.keys(settings.env).length === 0) {

package/lib/config-utils.js

@@ -5,9 +5,23 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const os = require('os');
 const { PLEXOR_DIR, CONFIG_PATH } = require('./constants');
 
 const DISABLED_HINT_VALUES = new Set(['', 'auto', 'none', 'off']);
+const VALID_ORCHESTRATION_MODES = new Set(['supervised', 'autonomous', 'danger-full-auto']);
+const VALID_ROUTING_MODES = new Set(['eco', 'balanced', 'quality', 'passthrough', 'cost']);
+const MANAGED_HEADER_KEYS = new Set([
+  'x-force-provider',
+  'x-force-model',
+  'x-allow-providers',
+  'x-deny-providers',
+  'x-allow-models',
+  'x-deny-models',
+  'x-plexor-mode',
+  'x-plexor-orchestration-mode'
+]);
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
 
 function normalizeForcedProvider(value) {
   if (typeof value !== 'string') {
@@ -31,6 +45,171 @@ function normalizeForcedModel(value) {
   return normalized;
 }
 
+function normalizeCsv(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const tokens = value
+    .split(',')
+    .map((token) => token.trim())
+    .filter(Boolean);
+  if (!tokens.length) {
+    return null;
+  }
+  return tokens.join(',');
+}
+
+function parseCustomHeaders(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) {
+    return {};
+  }
+  const trimmedRaw = raw.trim();
+
+  // Backward compatibility: older plugin versions persisted ANTHROPIC_CUSTOM_HEADERS
+  // as a JSON object string. Parse that first so managed key replacement works.
+  if (trimmedRaw.startsWith('{')) {
+    try {
+      const legacy = JSON.parse(trimmedRaw);
+      if (legacy && typeof legacy === 'object' && !Array.isArray(legacy)) {
+        const out = {};
+        for (const [key, value] of Object.entries(legacy)) {
+          const normalizedKey = String(key || '').trim().toLowerCase();
+          const normalizedValue = String(value ?? '').trim();
+          if (!normalizedKey || !normalizedValue) {
+            continue;
+          }
+          out[normalizedKey] = normalizedValue;
+        }
+        return out;
+      }
+    } catch {
+      // Fall through to line-based parser.
+    }
+  }
+
+  const parsed = {};
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const idx = trimmed.indexOf(':');
+    if (idx <= 0) {
+      continue;
+    }
+    const key = trimmed.slice(0, idx).trim().toLowerCase();
+    const value = trimmed.slice(idx + 1).trim();
+    if (!key || !value) {
+      continue;
+    }
+    parsed[key] = value;
+  }
+  return parsed;
+}
+
+function serializeCustomHeaders(headers) {
+  return Object.entries(headers)
+    .map(([key, value]) => `${key}: ${value}`)
+    .join('\n');
+}
+
+function buildManagedAnthropicHeaders(config) {
+  const settings = config?.settings || {};
+  const headers = {};
+
+  const modeRaw = String(settings.mode || '')
+    .trim()
+    .toLowerCase();
+  if (VALID_ROUTING_MODES.has(modeRaw)) {
+    headers['x-plexor-mode'] = modeRaw === 'cost' ? 'eco' : modeRaw;
+  }
+
+  const orchestrationRaw = String(
+    settings.orchestrationMode || settings.orchestration_mode || ''
+  )
+    .trim()
+    .toLowerCase();
+  if (VALID_ORCHESTRATION_MODES.has(orchestrationRaw)) {
+    headers['x-plexor-orchestration-mode'] = orchestrationRaw;
+  }
+
+  const forceProvider = normalizeForcedProvider(
+    settings.preferred_provider ?? settings.preferredProvider ?? 'auto'
+  );
+  if (forceProvider && forceProvider !== 'auto') {
+    headers['x-force-provider'] = forceProvider;
+  }
+
+  const forceModel = normalizeForcedModel(settings.preferred_model ?? settings.preferredModel);
+  if (forceModel) {
+    headers['x-force-model'] = forceModel;
+  }
+
+  const allowProviders = normalizeCsv(
+    settings.provider_allowlist ?? settings.providerAllowlist ?? ''
+  );
+  if (allowProviders) {
+    headers['x-allow-providers'] = allowProviders;
+  }
+
+  const denyProviders = normalizeCsv(settings.provider_denylist ?? settings.providerDenylist ?? '');
+  if (denyProviders) {
+    headers['x-deny-providers'] = denyProviders;
+  }
+
+  const allowModels = normalizeCsv(settings.model_allowlist ?? settings.modelAllowlist ?? '');
+  if (allowModels) {
+    headers['x-allow-models'] = allowModels;
+  }
+
+  const denyModels = normalizeCsv(settings.model_denylist ?? settings.modelDenylist ?? '');
+  if (denyModels) {
+    headers['x-deny-models'] = denyModels;
+  }
+
+  return headers;
+}
+
+function syncClaudeCustomHeaders(config) {
+  try {
+    let settings = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      const raw = fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf8');
+      settings = raw.trim() ? JSON.parse(raw) : {};
+    }
+
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+      settings = {};
+    }
+    settings.env = settings.env && typeof settings.env === 'object' ? settings.env : {};
+
+    const existing = parseCustomHeaders(settings.env.ANTHROPIC_CUSTOM_HEADERS);
+    for (const key of MANAGED_HEADER_KEYS) {
+      delete existing[key];
+    }
+
+    const managed = buildManagedAnthropicHeaders(config);
+    const merged = { ...existing, ...managed };
+
+    if (Object.keys(merged).length) {
+      settings.env.ANTHROPIC_CUSTOM_HEADERS = serializeCustomHeaders(merged);
+    } else {
+      delete settings.env.ANTHROPIC_CUSTOM_HEADERS;
+    }
+
+    const claudeDir = path.dirname(CLAUDE_SETTINGS_PATH);
+    if (!fs.existsSync(claudeDir)) {
+      fs.mkdirSync(claudeDir, { recursive: true, mode: 0o700 });
+    }
+    const tempPath = path.join(claudeDir, `.settings.${crypto.randomBytes(8).toString('hex')}.tmp`);
+    fs.writeFileSync(tempPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
+    fs.renameSync(tempPath, CLAUDE_SETTINGS_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function hasForcedHintConflict(config) {
   const settings = config?.settings || {};
   const provider = normalizeForcedProvider(
@@ -88,6 +267,8 @@ function saveConfig(config) {
     const tempPath = path.join(PLEXOR_DIR, `.config.${tempId}.tmp`);
     fs.writeFileSync(tempPath, JSON.stringify(config, null, 2), { mode: 0o600 });
     fs.renameSync(tempPath, CONFIG_PATH);
+    // Best-effort sync to Claude client headers so force hints are respected.
+    syncClaudeCustomHeaders(config);
     return true;
   } catch (err) {
     if (err.code === 'EACCES' || err.code === 'EPERM') {
@@ -121,4 +302,13 @@ function readSetting(config, configKey, configKeyAlt, envVar, validValues, defau
   return { value: defaultValue, source: 'default' };
 }
 
-module.exports = { loadConfig, saveConfig, readSetting, hasForcedHintConflict, validateForcedHintConfig };
+module.exports = {
+  loadConfig,
+  saveConfig,
+  readSetting,
+  hasForcedHintConflict,
+  validateForcedHintConfig,
+  parseCustomHeaders,
+  serializeCustomHeaders,
+  buildManagedAnthropicHeaders
+};

package/lib/settings-manager.js

@@ -22,6 +22,8 @@ const LOCK_TIMEOUT_MS = 5000; // 5 second lock timeout
 // Plexor gateway endpoints
 const PLEXOR_STAGING_URL = 'https://staging.api.plexor.dev/gateway/anthropic';
 const PLEXOR_PROD_URL = 'https://api.plexor.dev/gateway/anthropic';
+const PREVIOUS_API_KEY_ENV = 'PLEXOR_PREVIOUS_ANTHROPIC_API_KEY';
+const PREVIOUS_AUTH_TOKEN_ENV = 'PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN';
 
 /**
  * Check if a base URL is a Plexor-managed gateway URL.
@@ -39,6 +41,83 @@ function isManagedGatewayUrl(baseUrl) {
   );
 }
 
+function isPlexorApiKey(value = '') {
+  return typeof value === 'string' && value.startsWith('plx_');
+}
+
+function getPlexorAuthKey(env = {}) {
+  const apiKey = env.ANTHROPIC_API_KEY || '';
+  const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (isPlexorApiKey(apiKey)) return apiKey;
+  if (isPlexorApiKey(authToken)) return authToken;
+  return apiKey || authToken || '';
+}
+
+function hasPlexorManagedAuth(env = {}) {
+  return (
+    isManagedGatewayUrl(env.ANTHROPIC_BASE_URL || '') ||
+    isPlexorApiKey(env.ANTHROPIC_API_KEY || '') ||
+    isPlexorApiKey(env.ANTHROPIC_AUTH_TOKEN || '')
+  );
+}
+
+function stashDirectAuthEnv(env, plexorApiKey) {
+  const alreadyManaged = hasPlexorManagedAuth(env);
+  const currentApiKey = env.ANTHROPIC_API_KEY || '';
+  const currentAuthToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (currentApiKey && !isPlexorApiKey(currentApiKey) && currentApiKey !== plexorApiKey) {
+    env[PREVIOUS_API_KEY_ENV] = currentApiKey;
+  } else if (!alreadyManaged) {
+    delete env[PREVIOUS_API_KEY_ENV];
+  }
+
+  if (currentAuthToken && !isPlexorApiKey(currentAuthToken) && currentAuthToken !== plexorApiKey) {
+    env[PREVIOUS_AUTH_TOKEN_ENV] = currentAuthToken;
+  } else if (!alreadyManaged) {
+    delete env[PREVIOUS_AUTH_TOKEN_ENV];
+  }
+}
+
+function setPlexorAuthKey(env, apiKey) {
+  stashDirectAuthEnv(env, apiKey);
+  env.ANTHROPIC_API_KEY = apiKey;
+  env.ANTHROPIC_AUTH_TOKEN = apiKey;
+}
+
+function clearPlexorRoutingEnv(env = {}) {
+  const hasManagedBaseUrl = isManagedGatewayUrl(env.ANTHROPIC_BASE_URL || '');
+  const hasPlexorApiKey = isPlexorApiKey(env.ANTHROPIC_API_KEY || '');
+  const hasPlexorAuthToken = isPlexorApiKey(env.ANTHROPIC_AUTH_TOKEN || '');
+
+  if (!hasManagedBaseUrl && !hasPlexorApiKey && !hasPlexorAuthToken) {
+    return false;
+  }
+
+  if (hasManagedBaseUrl) {
+    delete env.ANTHROPIC_BASE_URL;
+  }
+  if (hasPlexorAuthToken) {
+    delete env.ANTHROPIC_AUTH_TOKEN;
+  }
+  if (hasPlexorApiKey) {
+    delete env.ANTHROPIC_API_KEY;
+  }
+
+  if (!env.ANTHROPIC_API_KEY && env[PREVIOUS_API_KEY_ENV]) {
+    env.ANTHROPIC_API_KEY = env[PREVIOUS_API_KEY_ENV];
+  }
+  if (!env.ANTHROPIC_AUTH_TOKEN && env[PREVIOUS_AUTH_TOKEN_ENV]) {
+    env.ANTHROPIC_AUTH_TOKEN = env[PREVIOUS_AUTH_TOKEN_ENV];
+  }
+
+  delete env[PREVIOUS_API_KEY_ENV];
+  delete env[PREVIOUS_AUTH_TOKEN_ENV];
+
+  return true;
+}
+
 class ClaudeSettingsManager {
   constructor() {
     this.settingsPath = SETTINGS_PATH;
@@ -171,8 +250,9 @@ class ClaudeSettingsManager {
   /**
    * Enable Plexor routing by setting env vars in settings.json
    *
-   * This is the KEY mechanism: setting ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
-   * in the env block redirects ALL Claude Code sessions to Plexor automatically.
+   * This is the KEY mechanism: setting ANTHROPIC_BASE_URL plus both Claude auth
+   * env vars in settings.json redirects ALL Claude Code sessions to Plexor
+   * automatically, even when the user previously configured direct API auth.
    *
    * @param {string} apiKey - Plexor API key (plx_*)
    * @param {Object} options - { useStaging: boolean }
@@ -191,10 +271,10 @@ class ClaudeSettingsManager {
         settings.env = {};
       }
 
-      // Set the magic environment variables
-      // ANTHROPIC_AUTH_TOKEN has higher precedence than ANTHROPIC_API_KEY
+      // Mirror the Plexor key into both Claude auth env vars so every Claude
+      // runtime path uses the gateway instead of any previously saved direct key.
       settings.env.ANTHROPIC_BASE_URL = apiUrl;
-      settings.env.ANTHROPIC_AUTH_TOKEN = apiKey;
+      setPlexorAuthKey(settings.env, apiKey);
 
       const success = this.save(settings);
 
@@ -229,9 +309,10 @@ class ClaudeSettingsManager {
         return true;
       }
 
-      // Remove Plexor-specific env vars
-      delete settings.env.ANTHROPIC_BASE_URL;
-      delete settings.env.ANTHROPIC_AUTH_TOKEN;
+      if (!clearPlexorRoutingEnv(settings.env)) {
+        console.log('Plexor routing is not currently enabled.');
+        return true;
+      }
 
       // Clean up empty env block
       if (Object.keys(settings.env).length === 0) {
@@ -262,7 +343,8 @@ class ClaudeSettingsManager {
       const settings = this.load();
 
       const baseUrl = settings.env?.ANTHROPIC_BASE_URL || null;
-      const hasToken = !!settings.env?.ANTHROPIC_AUTH_TOKEN;
+      const authKey = getPlexorAuthKey(settings.env);
+      const hasToken = !!authKey;
 
       // Check if routing to Plexor (any variant: prod, staging, localhost, tunnel)
       const isPlexorRouting = isManagedGatewayUrl(baseUrl);
@@ -272,7 +354,7 @@ class ClaudeSettingsManager {
         baseUrl,
         hasToken,
         isStaging: baseUrl?.includes('staging') || false,
-        tokenPreview: hasToken ? settings.env.ANTHROPIC_AUTH_TOKEN.substring(0, 12) + '...' : null
+        tokenPreview: hasToken ? authKey.substring(0, 12) + '...' : null
       };
     } catch {
       return { enabled: false, baseUrl: null, hasToken: false };
@@ -288,14 +370,14 @@ class ClaudeSettingsManager {
     try {
       const settings = this.load();
       const baseUrl = settings.env?.ANTHROPIC_BASE_URL || '';
-      const authToken = settings.env?.ANTHROPIC_AUTH_TOKEN || '';
+      const authKey = getPlexorAuthKey(settings.env);
       const isPlexorUrl = isManagedGatewayUrl(baseUrl);
 
-      if (isPlexorUrl && !authToken) {
-        return { partial: true, issue: 'Plexor URL set but no auth token' };
+      if (isPlexorUrl && !authKey) {
+        return { partial: true, issue: 'Plexor URL set but no Plexor auth key' };
       }
-      if (isPlexorUrl && !authToken.startsWith('plx_')) {
-        return { partial: true, issue: 'Plexor URL set but auth token is not a Plexor key' };
+      if (isPlexorUrl && !isPlexorApiKey(authKey)) {
+        return { partial: true, issue: 'Plexor URL set but auth key is not a Plexor key' };
       }
       return { partial: false, issue: null };
     } catch {
@@ -316,7 +398,7 @@ class ClaudeSettingsManager {
         settings.env = {};
       }
 
-      settings.env.ANTHROPIC_AUTH_TOKEN = apiKey;
+      setPlexorAuthKey(settings.env, apiKey);
       return this.save(settings);
     } catch (err) {
       console.error('Failed to update API key:', err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexor-dev/claude-code-plugin-staging",
-  "version": "0.1.0-beta.18",
+  "version": "0.1.0-beta.19",
   "description": "STAGING - LLM cost optimization plugin for Claude Code (internal testing)",
   "main": "lib/constants.js",
   "bin": {

package/scripts/postinstall.js

@@ -165,13 +165,39 @@ function isManagedGatewayUrl(baseUrl) {
  * Used to detect when a different variant was previously installed.
  */
 const THIS_VARIANT_URL = 'https://staging.api.plexor.dev/gateway/anthropic';
+const PREVIOUS_API_KEY_ENV = 'PLEXOR_PREVIOUS_ANTHROPIC_API_KEY';
+const PREVIOUS_AUTH_TOKEN_ENV = 'PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN';
 
 /**
  * Check for orphaned Plexor routing in settings.json without valid config.
  * Also detects variant mismatch (e.g., localhost plugin was installed, now
- * installing staging plugin) and migrates ANTHROPIC_BASE_URL + fixes
- * ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN (#2174).
+ * installing staging plugin) and migrates ANTHROPIC_BASE_URL + syncs
+ * Claude auth env vars for Plexor-managed gateways.
  */
+function selectManagedAuthKey(env = {}) {
+  const apiKey = env.ANTHROPIC_API_KEY || '';
+  const authToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (apiKey.startsWith('plx_')) return apiKey;
+  if (authToken.startsWith('plx_')) return authToken;
+  return apiKey || authToken || '';
+}
+
+function syncManagedAuthEnv(env, managedAuthKey) {
+  const currentApiKey = env.ANTHROPIC_API_KEY || '';
+  const currentAuthToken = env.ANTHROPIC_AUTH_TOKEN || '';
+
+  if (currentApiKey && !currentApiKey.startsWith('plx_') && currentApiKey !== managedAuthKey) {
+    env[PREVIOUS_API_KEY_ENV] = currentApiKey;
+  }
+  if (currentAuthToken && !currentAuthToken.startsWith('plx_') && currentAuthToken !== managedAuthKey) {
+    env[PREVIOUS_AUTH_TOKEN_ENV] = currentAuthToken;
+  }
+
+  env.ANTHROPIC_API_KEY = managedAuthKey;
+  env.ANTHROPIC_AUTH_TOKEN = managedAuthKey;
+}
+
 function checkOrphanedRouting() {
   // Use the resolved HOME_DIR (not process.env.HOME which may be wrong under sudo -u)
   const settingsPath = path.join(HOME_DIR, '.claude', 'settings.json');
@@ -187,21 +213,15 @@ function checkOrphanedRouting() {
     const hasPlexorUrl = isManagedGatewayUrl(env.ANTHROPIC_BASE_URL);
 
     if (hasPlexorUrl) {
-      // Fix #2174: Only migrate ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN
-      // when routing through a Plexor-managed URL. Non-Plexor setups
-      // (direct Anthropic, etc.) should not have their auth mutated.
-      if (env.ANTHROPIC_API_KEY && !env.ANTHROPIC_AUTH_TOKEN) {
-        env.ANTHROPIC_AUTH_TOKEN = env.ANTHROPIC_API_KEY;
-        delete env.ANTHROPIC_API_KEY;
-        settings.env = env;
-        settingsChanged = true;
-        console.log('\n  Migrated ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN (fix #2174)');
-      } else if (env.ANTHROPIC_API_KEY && env.ANTHROPIC_AUTH_TOKEN) {
-        // Both exist — remove the lower-precedence one to avoid confusion
-        delete env.ANTHROPIC_API_KEY;
+      // Keep both Claude auth env vars aligned to the Plexor key so Claude API
+      // auth cannot override the gateway after plugin setup.
+      const managedAuthKey = selectManagedAuthKey(env);
+      if (managedAuthKey &&
+          (env.ANTHROPIC_API_KEY !== managedAuthKey || env.ANTHROPIC_AUTH_TOKEN !== managedAuthKey)) {
+        syncManagedAuthEnv(env, managedAuthKey);
         settings.env = env;
         settingsChanged = true;
-        console.log('\n  Removed redundant ANTHROPIC_API_KEY (ANTHROPIC_AUTH_TOKEN takes precedence)');
+        console.log('\n  Synced Plexor auth into ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN');
       }
       // Check if there's a valid Plexor config
       let hasValidConfig = false;
@@ -385,11 +405,6 @@ function main() {
       chownRecursive(PLEXOR_CONFIG_DIR, uid, gid);
     }
 
-    // Detect shell type
-    const shell = process.env.SHELL || '';
-    const isZsh = shell.includes('zsh');
-    const shellRc = isZsh ? '~/.zshrc' : '~/.bashrc';
-
     // Print success message with clear onboarding steps
     console.log('');
     console.log('  ╔═══════════════════════════════════════════════════════════════════╗');
@@ -414,24 +429,18 @@ function main() {
     }
     console.log('');
 
-    // CRITICAL: Make the required step VERY obvious
     console.log('  ┌─────────────────────────────────────────────────────────────────┐');
-    console.log('  │  REQUIRED: Run this command to enable Plexor routing:          │');
+    console.log('  │  NEXT: Start Claude Code and run /plexor-setup                │');
     console.log('  └─────────────────────────────────────────────────────────────────┘');
     console.log('');
-    console.log('  For Claude MAX users (OAuth):');
-    console.log('');
-    console.log(`    echo 'export ANTHROPIC_BASE_URL="https://staging.api.plexor.dev/gateway/anthropic"' >> ${shellRc}`);
-    console.log(`    source ${shellRc}`);
-    console.log('');
-    console.log('  For API key users (get key at https://plexor.dev/dashboard):');
-    console.log('');
-    console.log(`    echo 'export ANTHROPIC_BASE_URL="https://staging.api.plexor.dev/gateway/anthropic"' >> ${shellRc}`);
-    console.log(`    echo 'export ANTHROPIC_AUTH_TOKEN="plx_your_key_here"' >> ${shellRc}`);
-    console.log(`    source ${shellRc}`);
+    console.log('  /plexor-setup will:');
+    console.log('    1. Ask for your Plexor API key');
+    console.log('    2. Write ~/.plexor/config.json');
+    console.log('    3. Point Claude at the Plexor staging gateway');
+    console.log('    4. Replace any existing Claude API env auth while Plexor is active');
     console.log('');
     console.log('  ┌─────────────────────────────────────────────────────────────────┐');
-    console.log('  │  Then start Claude Code and run: /plexor-status                │');
+    console.log('  │  No shell edits or Claude restart required after setup        │');
     console.log('  └─────────────────────────────────────────────────────────────────┘');
     console.log('');
     console.log('  Available commands:');

package/scripts/uninstall.js

@@ -57,6 +57,53 @@ const results = {
   pluginDir: false
 };
 
+function isManagedGatewayUrl(baseUrl = '') {
+  return (
+    baseUrl.includes('plexor') ||
+    baseUrl.includes('staging.api') ||
+    baseUrl.includes('localhost') ||
+    baseUrl.includes('127.0.0.1') ||
+    baseUrl.includes('ngrok') ||
+    baseUrl.includes('localtunnel')
+  );
+}
+
+function isPlexorApiKey(value = '') {
+  return typeof value === 'string' && value.startsWith('plx_');
+}
+
+function clearPlexorRoutingEnv(env = {}) {
+  const hasManagedBaseUrl = isManagedGatewayUrl(env.ANTHROPIC_BASE_URL || '');
+  const hasPlexorAuthToken = isPlexorApiKey(env.ANTHROPIC_AUTH_TOKEN || '');
+  const hasPlexorApiKey = isPlexorApiKey(env.ANTHROPIC_API_KEY || '');
+
+  if (!hasManagedBaseUrl && !hasPlexorAuthToken && !hasPlexorApiKey) {
+    return false;
+  }
+
+  if (hasManagedBaseUrl) {
+    delete env.ANTHROPIC_BASE_URL;
+  }
+  if (hasPlexorAuthToken) {
+    delete env.ANTHROPIC_AUTH_TOKEN;
+  }
+  if (hasPlexorApiKey) {
+    delete env.ANTHROPIC_API_KEY;
+  }
+
+  if (!env.ANTHROPIC_API_KEY && env.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY) {
+    env.ANTHROPIC_API_KEY = env.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY;
+  }
+  if (!env.ANTHROPIC_AUTH_TOKEN && env.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN) {
+    env.ANTHROPIC_AUTH_TOKEN = env.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN;
+  }
+
+  delete env.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY;
+  delete env.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN;
+
+  return true;
+}
+
 // 1. Remove routing from settings.json
 // This is CRITICAL - do NOT depend on settings-manager module since it may not load during uninstall
 try {
@@ -66,18 +113,14 @@ try {
     if (data && data.trim()) {
       const settings = JSON.parse(data);
       if (settings.env) {
-        const hadBaseUrl = !!settings.env.ANTHROPIC_BASE_URL;
-        const hadAuthToken = !!settings.env.ANTHROPIC_AUTH_TOKEN;
-
-        delete settings.env.ANTHROPIC_BASE_URL;
-        delete settings.env.ANTHROPIC_AUTH_TOKEN;
+        const routingChanged = clearPlexorRoutingEnv(settings.env);
 
         // Clean up empty env block
         if (Object.keys(settings.env).length === 0) {
           delete settings.env;
         }
 
-        if (hadBaseUrl || hadAuthToken) {
+        if (routingChanged) {
           fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
           results.routing = true;
         }