Lumoswitch Docs
Agent setup

Claude Code setup

Claude Code is Anthropic's coding agent. It can understand a project, edit files, run commands, and complete multi-step development work. Its LLM Gateway support lets those requests run through Lumoswitch.

The API configuration must enable Anthropic output, and the target model must genuinely support Anthropic Messages streaming and Tool Use. The CLI commands below target Bash or Zsh on macOS and Linux. Before continuing, confirm that claude --version returns a version number.

Choose a setup method

MethodBest forLocal writesStill active after exit?
One-time launchTesting a URL, Key, or modelTemporary Lumoswitch settings fileNo
Persistent useEveryday terminal useNative configuration + optional launcher and settings fileYes
Claude DesktopThe Code surface in Claude DesktopA separate app-managed Gateway configurationYes

The CLI and Claude Desktop are separate launch surfaces. One-time CLI parameters do not become Desktop configuration, and Desktop has no equivalent one-time launch command. The reason is explained below.

Prepare the connection values

PlaceholderValue
{{api_base_url}}The Anthropic request URL shown by the API configuration; do not append a path
{{access_key}}The API configuration's Access Key
{{model}}The client-facing model name shown by the API configuration
{{claude_settings_json}}Claude Code settings generated from effective reasoning capabilities
{{claude_model_capabilities}}Claude Code capability flags generated for the selected model

Commands copied from the console already contain real values. {{claude_settings_json}} includes the complete model list and sets effortLevel only when the default model's effective capabilities allow it. Do not use the upstream provider's original model ID.

One-time launch

This command creates a temporary model catalog for the newly started Claude Code process. It expires and is deleted when Claude Code exits, does not pollute the current shell, and does not change existing Claude Code settings.

(
  set -e
  LUMOSWITCH_CLAUDE_SETTINGS="$(mktemp "${TMPDIR:-/tmp}/lumoswitch-claude.XXXXXX")"
  trap 'rm -f "$LUMOSWITCH_CLAUDE_SETTINGS"' EXIT
  cat > "$LUMOSWITCH_CLAUDE_SETTINGS" <<'LUMOSWITCH_EOF'
{{claude_settings_json}}
LUMOSWITCH_EOF
  chmod 600 "$LUMOSWITCH_CLAUDE_SETTINGS"
  env \
    ANTHROPIC_BASE_URL="{{api_base_url}}" \
    ANTHROPIC_AUTH_TOKEN="{{access_key}}" \
    ANTHROPIC_MODEL="{{model}}" \
    ANTHROPIC_DEFAULT_FABLE_MODEL="{{model}}" \
    ANTHROPIC_DEFAULT_OPUS_MODEL="{{model}}" \
    ANTHROPIC_DEFAULT_SONNET_MODEL="{{model}}" \
    ANTHROPIC_DEFAULT_HAIKU_MODEL="{{model}}" \
    CLAUDE_CODE_SUBAGENT_MODEL="{{model}}" \
    ANTHROPIC_CUSTOM_MODEL_OPTION="{{model}}" \
    ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES="{{claude_model_capabilities}}" \
    CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1" \
    claude --settings "$LUMOSWITCH_CLAUDE_SETTINGS" --model "{{model}}"
)

Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. The family and subagent variables keep the main session, Fable/Opus/Sonnet/Haiku aliases, background work, and subagents on the same client-facing model. Gateway discovery exposes /v1/models, while the generated capability declaration enables only reasoning controls verified for the selected route.

Persistent use

Run the complete command during initial setup and whenever the URL, Access Key, or model changes. It preserves the existing Claude Code user settings for cleanup, writes the native persistent settings, and saves an optional Lumoswitch maintenance launcher.

Persistent import stores the Access Key in an owner-only managed environment or Agent configuration file. Use it only on a trusted personal device.

set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/claude-code"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-claude-code"
mkdir -p "$LUMOSWITCH_ROOT/original" "$(dirname "$LUMOSWITCH_LAUNCHER")"
umask 077

preserve_lumoswitch_original() {
  LUMOSWITCH_NATIVE_FILE="$1"
  LUMOSWITCH_ORIGINAL_NAME="$2"
  LUMOSWITCH_STATE="$LUMOSWITCH_ROOT/original/$LUMOSWITCH_ORIGINAL_NAME.state"
  if [ -f "$LUMOSWITCH_STATE" ]; then return; fi
  if [ -f "$LUMOSWITCH_NATIVE_FILE" ]; then
    cp "$LUMOSWITCH_NATIVE_FILE" "$LUMOSWITCH_ROOT/original/$LUMOSWITCH_ORIGINAL_NAME"
    printf '%s\n' present > "$LUMOSWITCH_STATE"
  else
    printf '%s\n' absent > "$LUMOSWITCH_STATE"
  fi
}

if [ -f "$LUMOSWITCH_LAUNCHER" ]; then
  LUMOSWITCH_BACKUP="$LUMOSWITCH_LAUNCHER.backup.$(date +%Y%m%d-%H%M%S)-$$"
  cp "$LUMOSWITCH_LAUNCHER" "$LUMOSWITCH_BACKUP"
  chmod 600 "$LUMOSWITCH_BACKUP"
fi

LUMOSWITCH_CLAUDE_SETTINGS="$HOME/.claude/settings.json"
mkdir -p "$(dirname "$LUMOSWITCH_CLAUDE_SETTINGS")"
preserve_lumoswitch_original "$LUMOSWITCH_CLAUDE_SETTINGS" settings
cat > "$LUMOSWITCH_CLAUDE_SETTINGS" <<'LUMOSWITCH_CONFIG_EOF'
{{claude_settings_json}}
LUMOSWITCH_CONFIG_EOF

cat > "$LUMOSWITCH_ENV" <<'LUMOSWITCH_ENV_EOF'
export ANTHROPIC_BASE_URL="{{api_base_url}}"
export ANTHROPIC_AUTH_TOKEN="{{access_key}}"
export ANTHROPIC_MODEL="{{model}}"
export ANTHROPIC_DEFAULT_FABLE_MODEL="{{model}}"
export ANTHROPIC_DEFAULT_OPUS_MODEL="{{model}}"
export ANTHROPIC_DEFAULT_SONNET_MODEL="{{model}}"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="{{model}}"
export CLAUDE_CODE_SUBAGENT_MODEL="{{model}}"
export ANTHROPIC_CUSTOM_MODEL_OPTION="{{model}}"
export ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES="{{claude_model_capabilities}}"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
LUMOSWITCH_ENV_EOF

case "$SHELL" in
  */zsh) LUMOSWITCH_PROFILE="$HOME/.zshrc" ;;
  */bash) LUMOSWITCH_PROFILE="$HOME/.bashrc" ;;
  *) LUMOSWITCH_PROFILE="$HOME/.profile" ;;
esac
touch "$LUMOSWITCH_PROFILE"
LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: claude-code'
LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/claude-code/env.sh" ] && . "$HOME/.config/lumoswitch/agents/claude-code/env.sh"'
if ! grep -Fqx "$LUMOSWITCH_SOURCE_LINE" "$LUMOSWITCH_PROFILE"; then
  printf '\n%s\n%s\n' "$LUMOSWITCH_PROFILE_MARKER" "$LUMOSWITCH_SOURCE_LINE" >> "$LUMOSWITCH_PROFILE"
fi
printf '%s\n' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_ROOT/profile-path"

cat > "$LUMOSWITCH_LAUNCHER" <<'LUMOSWITCH_LAUNCHER_EOF'
#!/usr/bin/env bash
set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/claude-code"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-claude-code"

restore_lumoswitch_original() {
  LUMOSWITCH_NATIVE_FILE="$1"
  LUMOSWITCH_ORIGINAL_NAME="$2"
  LUMOSWITCH_STATE="$LUMOSWITCH_ROOT/original/$LUMOSWITCH_ORIGINAL_NAME.state"
  if [ ! -f "$LUMOSWITCH_STATE" ]; then return; fi
  if [ "$(cat "$LUMOSWITCH_STATE")" = present ]; then
    mkdir -p "$(dirname "$LUMOSWITCH_NATIVE_FILE")"
    cp "$LUMOSWITCH_ROOT/original/$LUMOSWITCH_ORIGINAL_NAME" "$LUMOSWITCH_NATIVE_FILE"
  else
    rm -f "$LUMOSWITCH_NATIVE_FILE"
  fi
}

if [ "$1" = "--lumoswitch-clean" ]; then
  if [ -f "$LUMOSWITCH_ROOT/profile-path" ]; then
    LUMOSWITCH_PROFILE="$(cat "$LUMOSWITCH_ROOT/profile-path")"
    if [ -f "$LUMOSWITCH_PROFILE" ]; then
      LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: claude-code'
      LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/claude-code/env.sh" ] && . "$HOME/.config/lumoswitch/agents/claude-code/env.sh"'
      LUMOSWITCH_PROFILE_TMP="$LUMOSWITCH_PROFILE.lumoswitch.$$"
      awk -v marker="$LUMOSWITCH_PROFILE_MARKER" -v source="$LUMOSWITCH_SOURCE_LINE" '$0 != marker && $0 != source' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_PROFILE_TMP"
      mv "$LUMOSWITCH_PROFILE_TMP" "$LUMOSWITCH_PROFILE"
    fi
  fi
  restore_lumoswitch_original "$HOME/.claude/settings.json" settings
  if [ -d "$LUMOSWITCH_ROOT" ]; then
    find "$LUMOSWITCH_ROOT" -depth \( -type f -o -type l \) -delete
    find "$LUMOSWITCH_ROOT" -depth -type d -exec rmdir {} \; 2>/dev/null || true
  fi
  find "$(dirname "$LUMOSWITCH_LAUNCHER")" -maxdepth 1 -type f -name 'lumoswitch-claude-code.backup.*' -delete
  rm -f "$LUMOSWITCH_LAUNCHER"
  printf '%s\n' 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
fi

if [ -f "$LUMOSWITCH_ENV" ]; then . "$LUMOSWITCH_ENV"; fi
exec claude "$@"
LUMOSWITCH_LAUNCHER_EOF

chmod 600 "$LUMOSWITCH_ENV"
find "$LUMOSWITCH_ROOT" -type f -exec chmod 600 {} \;
chmod 700 "$LUMOSWITCH_LAUNCHER"
. "$LUMOSWITCH_ENV"
printf '%s\n' 'Native Lumoswitch setup saved. Future command: claude'
printf '%s\n' 'Optional maintenance launcher: ~/.local/bin/lumoswitch-claude-code'
claude

For everyday use, run this from any project directory:

claude

The native claude command reads the managed settings and environment without displaying the Access Key. An update first keeps a timestamped backup with 0600 permissions, then writes the new launcher with 0700 permissions.

Native Windows PowerShell import

These commands run natively in Windows PowerShell without WSL and use the same connection values as the macOS/Linux templates on this page.

One-time use on Windows

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchConfig = Join-Path ([IO.Path]::GetTempPath()) ('lumoswitch-' + [Guid]::NewGuid().ToString('N') + '.json')
  $lumoswitchConfigContent = @'
{{claude_settings_json}}
'@
  [IO.File]::WriteAllText($lumoswitchConfig, $lumoswitchConfigContent, [Text.UTF8Encoding]::new($false))
  $lumoswitchEnvironmentNames = @('ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_FABLE_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL', 'ANTHROPIC_CUSTOM_MODEL_OPTION', 'ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES', 'CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY')
  $lumoswitchPreviousEnvironment = @{}
  foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
    $lumoswitchPreviousEnvironment[$lumoswitchName] = [Environment]::GetEnvironmentVariable($lumoswitchName, 'Process')
  }
  $lumoswitchExitCode = 0
  try {
    [Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', '{{api_base_url}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', '{{access_key}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_FABLE_MODEL', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_SONNET_MODEL', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_HAIKU_MODEL', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('CLAUDE_CODE_SUBAGENT_MODEL', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_CUSTOM_MODEL_OPTION', '{{model}}', 'Process')
    [Environment]::SetEnvironmentVariable('ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES', '{{claude_model_capabilities}}', 'Process')
    [Environment]::SetEnvironmentVariable('CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY', '1', 'Process')
    $lumoswitchArguments = @('--settings', $lumoswitchConfig, '--model', '{{model}}')
    $lumoswitchExecutable = Get-Command 'claude.cmd' -CommandType Application -ErrorAction SilentlyContinue
    if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'claude' -CommandType Application -ErrorAction Stop }
    & $lumoswitchExecutable.Path @lumoswitchArguments
    if ($null -ne $LASTEXITCODE) { $lumoswitchExitCode = $LASTEXITCODE }
  } finally {
    foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
      [Environment]::SetEnvironmentVariable($lumoswitchName, $lumoswitchPreviousEnvironment[$lumoswitchName], 'Process')
    }
    Remove-Item -LiteralPath $lumoswitchConfig -Force -ErrorAction SilentlyContinue
  }
  if ($lumoswitchExitCode -ne 0) { throw 'claude exited with code ' + $lumoswitchExitCode }
}

Persistent use on Windows

This command backs up existing Lumoswitch-owned files and restricts access to the configuration and launcher for the current user.

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\claude-code'
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-claude-code.ps1'
  $lumoswitchBackupSuffix = (Get-Date -Format 'yyyyMMdd-HHmmss') + '-' + $PID

  function Protect-LumoswitchFile([string] $Path) {
    $lumoswitchSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
    & icacls.exe $Path '/inheritance:r' '/grant:r' ('*' + $lumoswitchSid + ':(F)') '*S-1-5-18:(F)' '*S-1-5-32-544:(F)' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw "Could not restrict access to $Path" }
  }

  function Install-LumoswitchFile([string] $Path, [string] $Content) {
    [IO.Directory]::CreateDirectory((Split-Path -Parent $Path)) | Out-Null
    if (Test-Path -LiteralPath $Path) {
      $lumoswitchItem = Get-Item -LiteralPath $Path -Force
      if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
        throw "Lumoswitch refused to replace a directory or link: $Path"
      }
      $lumoswitchBackup = $Path + '.backup.' + $lumoswitchBackupSuffix
      Copy-Item -LiteralPath $Path -Destination $lumoswitchBackup
      Protect-LumoswitchFile $lumoswitchBackup
    }
    $lumoswitchTemporary = $Path + '.' + [Guid]::NewGuid().ToString('N') + '.tmp'
    try {
      [IO.File]::WriteAllText($lumoswitchTemporary, $Content, [Text.UTF8Encoding]::new($false))
      Move-Item -LiteralPath $lumoswitchTemporary -Destination $Path -Force
      Protect-LumoswitchFile $Path
    } finally {
      Remove-Item -LiteralPath $lumoswitchTemporary -Force -ErrorAction SilentlyContinue
    }
  }

  function Preserve-LumoswitchOriginal([string] $Path, [string] $Name) {
    $lumoswitchOriginalRoot = Join-Path $lumoswitchRoot 'original'
    $lumoswitchState = Join-Path $lumoswitchOriginalRoot ($Name + '.state')
    if (Test-Path -LiteralPath $lumoswitchState -PathType Leaf) { return }
    [IO.Directory]::CreateDirectory($lumoswitchOriginalRoot) | Out-Null
    if (Test-Path -LiteralPath $Path -PathType Leaf) {
      $lumoswitchOriginal = Join-Path $lumoswitchOriginalRoot $Name
      Copy-Item -LiteralPath $Path -Destination $lumoswitchOriginal
      Protect-LumoswitchFile $lumoswitchOriginal
      [IO.File]::WriteAllText($lumoswitchState, 'present', [Text.UTF8Encoding]::new($false))
    } else {
      [IO.File]::WriteAllText($lumoswitchState, 'absent', [Text.UTF8Encoding]::new($false))
    }
    Protect-LumoswitchFile $lumoswitchState
  }

  [IO.Directory]::CreateDirectory($lumoswitchRoot) | Out-Null
  $lumoswitchConfig = Join-Path $HOME '.claude\settings.json'
  Preserve-LumoswitchOriginal $lumoswitchConfig 'settings'
  $lumoswitchConfigContent = @'
{{claude_settings_json}}
'@
  Install-LumoswitchFile $lumoswitchConfig $lumoswitchConfigContent

  $lumoswitchEnvironment = [ordered]@{}
  $lumoswitchEnvironment['ANTHROPIC_BASE_URL'] = '{{api_base_url}}'
  $lumoswitchEnvironment['ANTHROPIC_AUTH_TOKEN'] = '{{access_key}}'
  $lumoswitchEnvironment['ANTHROPIC_MODEL'] = '{{model}}'
  $lumoswitchEnvironment['ANTHROPIC_DEFAULT_FABLE_MODEL'] = '{{model}}'
  $lumoswitchEnvironment['ANTHROPIC_DEFAULT_OPUS_MODEL'] = '{{model}}'
  $lumoswitchEnvironment['ANTHROPIC_DEFAULT_SONNET_MODEL'] = '{{model}}'
  $lumoswitchEnvironment['ANTHROPIC_DEFAULT_HAIKU_MODEL'] = '{{model}}'
  $lumoswitchEnvironment['CLAUDE_CODE_SUBAGENT_MODEL'] = '{{model}}'
  $lumoswitchEnvironment['ANTHROPIC_CUSTOM_MODEL_OPTION'] = '{{model}}'
  $lumoswitchEnvironment['ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES'] = '{{claude_model_capabilities}}'
  $lumoswitchEnvironment['CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY'] = '1'
  foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
  }

  $lumoswitchLauncherContent = @'
param([Parameter(ValueFromRemainingArguments = $true)][string[]] $AgentArgs)
$ErrorActionPreference = 'Stop'
$lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\claude-code'
$lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-claude-code.ps1'

function Remove-LumoswitchFile([string] $Path) {
  if (-not (Test-Path -LiteralPath $Path)) { return }
  $lumoswitchItem = Get-Item -LiteralPath $Path -Force
  if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
    throw "Lumoswitch refused to remove a directory or link: $Path"
  }
  Remove-Item -LiteralPath $Path -Force
}

function Restore-LumoswitchOriginal([string] $Path, [string] $Name) {
  $lumoswitchOriginalRoot = Join-Path $lumoswitchRoot 'original'
  $lumoswitchState = Join-Path $lumoswitchOriginalRoot ($Name + '.state')
  if (-not (Test-Path -LiteralPath $lumoswitchState -PathType Leaf)) { return }
  if ((Get-Content -LiteralPath $lumoswitchState -Raw).Trim() -eq 'present') {
    [IO.Directory]::CreateDirectory((Split-Path -Parent $Path)) | Out-Null
    Copy-Item -LiteralPath (Join-Path $lumoswitchOriginalRoot $Name) -Destination $Path -Force
  } else {
    Remove-LumoswitchFile $Path
  }
}

if ($AgentArgs.Count -gt 0 -and $AgentArgs[0] -eq '--lumoswitch-clean') {
  foreach ($lumoswitchName in @('ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_FABLE_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL', 'ANTHROPIC_CUSTOM_MODEL_OPTION', 'ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES', 'CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY')) {
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'Process')
  }
  Restore-LumoswitchOriginal (Join-Path $HOME '.claude\settings.json') 'settings'
  # No external Lumoswitch file needs removal.
  if (Test-Path -LiteralPath $lumoswitchRoot -PathType Container) {
    $lumoswitchRootItem = Get-Item -LiteralPath $lumoswitchRoot -Force
    if ($lumoswitchRootItem.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Lumoswitch refused to clean through a linked directory.' }
    foreach ($lumoswitchFile in @(Get-ChildItem -LiteralPath $lumoswitchRoot -File -Recurse -Force)) { Remove-LumoswitchFile $lumoswitchFile.FullName }
    foreach ($lumoswitchDirectory in @(Get-ChildItem -LiteralPath $lumoswitchRoot -Directory -Recurse -Force | Sort-Object FullName -Descending)) {
      if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchDirectory.FullName -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchDirectory.FullName -Force }
    }
    if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchRoot -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchRoot -Force }
  }
  $lumoswitchBin = Split-Path -Parent $lumoswitchLauncher
  if (Test-Path -LiteralPath $lumoswitchBin -PathType Container) {
    foreach ($lumoswitchBackup in @(Get-ChildItem -LiteralPath $lumoswitchBin -Filter 'lumoswitch-claude-code.ps1.backup.*' -File -Force)) { Remove-LumoswitchFile $lumoswitchBackup.FullName }
  }
  Remove-LumoswitchFile $lumoswitchLauncher
  Write-Host 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
}

$lumoswitchEnvironment = [ordered]@{}
$lumoswitchEnvironment['ANTHROPIC_BASE_URL'] = '{{api_base_url}}'
$lumoswitchEnvironment['ANTHROPIC_AUTH_TOKEN'] = '{{access_key}}'
$lumoswitchEnvironment['ANTHROPIC_MODEL'] = '{{model}}'
$lumoswitchEnvironment['ANTHROPIC_DEFAULT_FABLE_MODEL'] = '{{model}}'
$lumoswitchEnvironment['ANTHROPIC_DEFAULT_OPUS_MODEL'] = '{{model}}'
$lumoswitchEnvironment['ANTHROPIC_DEFAULT_SONNET_MODEL'] = '{{model}}'
$lumoswitchEnvironment['ANTHROPIC_DEFAULT_HAIKU_MODEL'] = '{{model}}'
$lumoswitchEnvironment['CLAUDE_CODE_SUBAGENT_MODEL'] = '{{model}}'
$lumoswitchEnvironment['ANTHROPIC_CUSTOM_MODEL_OPTION'] = '{{model}}'
$lumoswitchEnvironment['ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES'] = '{{claude_model_capabilities}}'
$lumoswitchEnvironment['CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY'] = '1'
foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
  [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
}
$lumoswitchExecutable = Get-Command 'claude.cmd' -CommandType Application -ErrorAction SilentlyContinue
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'claude.exe' -CommandType Application -ErrorAction SilentlyContinue }
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'claude' -CommandType Application -ErrorAction Stop }
$lumoswitchArguments = @()
& $lumoswitchExecutable.Path @lumoswitchArguments @AgentArgs
if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }
'@
  Install-LumoswitchFile $lumoswitchLauncher $lumoswitchLauncherContent
  Write-Host 'Native Lumoswitch setup saved. Future command: claude'
  Write-Host 'Optional maintenance launcher:' $lumoswitchLauncher
  $lumoswitchExecutable = Get-Command 'claude.cmd' -CommandType Application -ErrorAction SilentlyContinue
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'claude.exe' -CommandType Application -ErrorAction SilentlyContinue }
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'claude' -CommandType Application -ErrorAction Stop }
  $lumoswitchArguments = @()
  & $lumoswitchExecutable.Path @lumoswitchArguments
  if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { throw 'claude exited with code ' + $LASTEXITCODE }
}

The import writes the Agent-supported persistent configuration and starts claude directly. The saved Lumoswitch maintenance script is not required to start the Agent; run it with --lumoswitch-clean when you need to restore or remove this setup.

Remove the Lumoswitch setup

Windows PowerShell

Exit every Lumoswitch session for this Agent, then run the command below. The optional maintenance launcher removes the managed native configuration, restores any preserved shared file, clears Lumoswitch user environment values, and removes itself.

& {
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-claude-code.ps1'
  if (-not (Test-Path -LiteralPath $lumoswitchLauncher -PathType Leaf)) {
    throw 'The optional Lumoswitch maintenance launcher is missing. Run persistent import again before cleanup.'
  }
  & powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File $lumoswitchLauncher --lumoswitch-clean
}

macOS / Linux

The following command disables persistent CLI use, restores the preserved Claude settings when present, and removes the managed environment hook and optional launcher. It does not delete Claude Code accounts, sessions, project memory, or existing configuration.

"$HOME/.local/bin/lumoswitch-claude-code" --lumoswitch-clean

The one-time command scopes its variables to the Claude Code child process, so nothing remains after it exits. After removal, run claude directly to return to the original Claude Code login or provider configuration.

Claude Desktop and IDEs

Claude Desktop

The Code surface in Claude Desktop is an official graphical interface, but it does not read the CLI launch parameters above. Configure it separately under Developer → Configure Third-Party Inference by selecting Gateway and entering the Lumoswitch URL, Access Key, and client-facing model name.

This surface offers persistent setup only. There is no temporary command because Desktop starts from application-managed configuration rather than accepting one-off claude --model ... arguments. To remove it, restore the default inference channel or remove the Gateway in Desktop. Deleting the CLI launcher does not remove Desktop configuration.

The Gateway must support POST /v1/messages, streaming, and Tool Use. Regular Claude Chat and Cowork are not the Claude Code surface. See Claude Desktop Gateway.

VS Code and JetBrains

Claude Code has official VS Code and JetBrains integrations. The one-time command affects only the CLI process it starts. After persistent import, restart the IDE so its terminal and graphical integration inherit the native settings and managed environment.

Claude Code shares ~/.claude/settings.json between its CLI and IDE extensions. Persistent import replaces that user file only while Lumoswitch is active, after preserving the original for exact cleanup restoration; one-time import leaves it untouched. If you later save Lumoswitch environment variables in an IDE-specific setting, remove those entries separately when disconnecting. See Claude Code IDE integration.

Verify and troubleshoot

  • Use the URL provided by the API configuration. Do not append /v1 or /messages.
  • If Claude sign-in still appears, confirm that you did not replace ANTHROPIC_AUTH_TOKEN with ANTHROPIC_API_KEY.
  • Protocol translation cannot add missing model capabilities. Verify streaming, file edits, and subagents before relying on the setup.

References: LLM Gateway, model configuration, and environment variables.

Maintainer publication fields
  • Platform ID: claude-code
  • Display name: Claude Code CLI
  • Downstream protocol: anthropic
  • commandTemplate: copy the complete One-time launch code block
  • Persistent strategy: native
  • persistentCommandTemplate: copy the complete Persistent use code block
  • futureCommand: claude
  • Display order: 20
  • Last verified: 2026-08-27

Mistral Vibe setup

Connect Vibe Code CLI and its editor surfaces to Lumoswitch with an isolated provider profile

GitHub Copilot CLI setup

Understand GitHub Copilot CLI and choose one-time, persistent, or removal instructions for Lumoswitch

On this page

Claude Code setupChoose a setup methodPrepare the connection valuesOne-time launchPersistent useNative Windows PowerShell importOne-time use on WindowsPersistent use on WindowsRemove the Lumoswitch setupWindows PowerShellmacOS / LinuxClaude Desktop and IDEsClaude DesktopVS Code and JetBrainsVerify and troubleshoot